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.
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
Errors
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Original filename; sanitized and embedded in the generated S3 key.
MIME type stored on the file row and set as the presigned PUT's Content-Type.
Client-reported size in bytes; stored as-is, not verified against the uploaded object.
Destination folder id; omit to upload to the Files root.
Tag strings to store on the file row.
Optional one-line description; can also be filled in later via generate-description.
If set together with entity_id, attaches the file to this CRM entity as part of the same call.
If set together with entity_type, attaches the file to this CRM entity as part of the same call.
Response
Successful Response
The response is of type Response Upload Init Files Upload Init Post · object.