curl --request POST \
  --url https://go.aiinsurance.io/api/v1/companies/{companyId}/files \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityType": "company",
  "fileName": "master-agreement.pdf",
  "contentType": "application/pdf",
  "byteSize": 482133
}
'

{
  "fileId": "550e8400-e29b-41d4-a716-446655440020",
  "versionId": "550e8400-e29b-41d4-a716-446655440021",
  "uploadUrl": "https://storage.googleapis.com/bucket/companies/.../files/...?X-Goog-Expires=900&X-Goog-Signature=..."
}

Uploads

Create Upload Intent

Phase 1 of the two-phase upload: declare the file (owner, name, MIME type, exact byte size) and receive a short-lived signed uploadUrl pinned to the declared content type and byte size.

To complete the upload:

PUT the raw bytes to uploadUrl with TWO headers, both signed into the URL (the storage host rejects the request without them): Content-Type: <the contentType you declared> and x-goog-content-length-range: <byteSize>,<byteSize>. Bytes go straight to cloud storage — never through this API.
POST /files/{fileId}/finalize with the returned versionId to make the file visible.

Until finalize the file’s status is pending and it appears in no listing. The signed URL expires after 15 minutes; abandoned pending uploads are reclaimed automatically.

Files belong to an owner: a configured entity (entityType + entityId) or the whole company (entityType: "company", no entityId). Optionally place the file inside one of the owner’s folders with folderId.

Required permission: company.file:create

POST

api

companies

{companyId}

files

curl --request POST \
  --url https://go.aiinsurance.io/api/v1/companies/{companyId}/files \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityType": "company",
  "fileName": "master-agreement.pdf",
  "contentType": "application/pdf",
  "byteSize": 482133
}
'

{
  "fileId": "550e8400-e29b-41d4-a716-446655440020",
  "versionId": "550e8400-e29b-41d4-a716-446655440021",
  "uploadUrl": "https://storage.googleapis.com/bucket/companies/.../files/...?X-Goog-Expires=900&X-Goog-Signature=..."
}

Authorizations

Authorization

string

header

required

API key authentication. Send your raw API key as the Authorization header value with NO scheme prefix — Authorization: YOUR-API-KEY. Do NOT prefix it with Bearer or ApiKey, and do not use an X-API-Key header; those are not accepted.

Path Parameters

companyId

string<uuid>

required

Company identifier

Body

application/json

entityType

enum<string>

required

The file owner's entity type

Available options:

event,

exposure,

quote,

submission,

person,

organization,

policy,

company

fileName

string

required

File name (must be non-empty)

contentType

string

required

MIME type of the file (e.g. application/pdf); must be an allowed type

byteSize

integer

required

Exact size of the upload in bytes (max 104857600 = 100 MiB)

entityId

string<uuid> | null

The owner entity's id. Required for every entityType except company (omit or send null for company-level files).

folderId

string<uuid> | null

Folder to place the file in (omit or null for the owner's top level)

displayDate

string<date-time>

Optional back-datable "as of" ISO 8601 timestamp. When set, file listings display and sort the file by this date instead of its upload time — intended for historical imports and integrations. The audit timestamps and uploader attribution stay server-set.

displayAuthor

string

Optional user-visible uploader label (trimmed; must be non-empty). When set, the file is presented as uploaded by this label instead of the uploader's name — intended for historical imports carrying the source system's author (or a marker like "Data Import"). Uploader attribution stays server-set.

Maximum string length: 255

Response

Upload intent created — PUT the bytes to uploadUrl, then finalize

fileId

string<uuid>

Id of the created file (still pending)

versionId

string<uuid>

Id of the pending version — pass it to finalize

uploadUrl

string

Short-lived signed URL to PUT the file bytes to (expires in 15 minutes)

⌘I

Getting Started

User

Entities

Event Lifecycle

Policy Transactions

Financials

Rating

Notes

Tasks

Configuration Management

Company Files

Forms

Document Generation

Submission Parsing

Reference

Create Upload Intent

Authorizations

Path Parameters

Body

Response