Initiate an Upload

Step 1 of the two-step upload flow.

Creates the files metadata row and returns a presigned PUT URL. The browser must PUT the file bytes directly to upload_url. On success the frontend should call onUploadComplete with the file_id.

POST /files/upload-init

Upload Init

cURL

curl --request POST \
  --url https://api.example.com/files/upload-init \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "<string>",
  "content_type": "application/octet-stream",
  "size_bytes": 123,
  "folder_id": "<string>",
  "tags": [],
  "description": "<string>",
  "entity_type": "<string>",
  "entity_id": "<string>"
}
'

200

{}

New to files? See the Files & Folders guide for the upload model and how attachments work. This page is the field-level technical reference.

Step 1 of the upload flow. Creates the files row with status: "pending" and returns a presigned PUT URL valid for 15 minutes. The caller uploads the raw bytes directly to upload_url, then calls Confirm an Upload, which verifies the object landed and flips the row to status: "uploaded".

Get a Download URL and Get Extracted Text Content reject a still-pending file with 409. Generate an AI Description does not — it never checks status, and on a pending file the missing S3 object is swallowed during text extraction, so it returns 200 with a description derived from the filename alone and persists it. Confirm the upload before asking for a description.

The presigned upload URL is signed against the exact content_type you send here. If the client’s PUT request uses a different Content-Type header than what was passed to this call, S3 rejects the request with a signature mismatch — the header must match exactly, not be inferred by the HTTP client.

Attachments are a many-to-many join, not a field on the file (see Attach a File to an Entity). Setting entity_type and entity_id here creates the first attachment inline as part of this same call — but setting only one of the pair is a silent no-op, no attachment is created and no error is raised.

Auth

Requires a CRM manage scope and an active organization on the token. Any *:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.

Response

Field	Type	Description
upload_url	string	Presigned S3 PUT URL, expires in 900 seconds.
key	string	The S3 object key the client must PUT to. Same value as file.s3_key.
file_id	string (uuid)	The new file’s id.
file	object	The full created files row (status: "pending").

Errors

Status	Cause
404 Not Found	folder_id doesn’t exist (or isn’t in this org / is archived).
502 Bad Gateway	Could not generate the presigned URL, or the database insert failed.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

filename · string · required

Original filename; sanitized and embedded in the generated S3 key.

content_type · string · default: application/octet-stream

MIME type stored on the file row and set as the presigned PUT's Content-Type.

size_bytes · integer | null

Client-reported size in bytes; stored as-is, not verified against the uploaded object.

folder_id · string | null

Destination folder id; omit to upload to the Files root.

tags · string[]

Tag strings to store on the file row.

description · string | null

Optional one-line description; can also be filled in later via generate-description.

entity_type · string | null

If set together with entity_id, attaches the file to this CRM entity as part of the same call.

entity_id · string | null

If set together with entity_type, attaches the file to this CRM entity as part of the same call.

Response

200

application/json

Successful Response

The response is of type Response Upload Init Files Upload Init Post · object.