curl --request POST \
  --url https://app.aiinsurance.io/api/v1/external/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=..."
}

Company Files

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

external

companies

{companyId}

files

curl --request POST \
  --url https://app.aiinsurance.io/api/v1/external/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)

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)

Overview Finalize Upload

⌘I