files_upload
Reserve presigned uploads for 1–10 LOCAL files (an image carousel is one call).
Reserve presigned uploads for 1–10 LOCAL files (an image carousel is one call). For each file, PUT the raw bytes to its upload.url with the returned Content-Type header (e.g. curl -T photo.jpg -H 'Content-Type: image/jpeg' '<url>'), then poll files_get (or files_list with ids) until readiness leaves ‘processing’ — there is NO complete call; the server finalizes when the bytes land. Requires a runtime that can PUT raw bytes to a URL (CLI agents). Chat-hosted agents that cannot PUT should instead pass a public https:// URL in posts_create’s media list.
Input
| Field | Type | Required | Description |
|---|---|---|---|
organization | string | no | Organization slug to act in (see organizations_list). Optional: API keys are bound to one organization; OAuth connections default to your active organization. |
files | array | yes | 1–10 files, all-or-nothing: an invalid entry fails the whole call with its index and nothing is created. After creation each file is independent. |
idempotency_key | string | no | Client-chosen dedupe key. Retrying with the same key returns the original result instead of creating/publishing twice. Pick one per logical action. |
Set idempotency_key on retries: a repeated call with the same key returns the original result instead of acting twice. Use it whenever you cannot tell whether a timed-out call landed.
Result
JSON on success. A refusal comes back as an error prefixed with its code (NOT_FOUND, FORBIDDEN, TOO_MANY_REQUESTS, …) and a message written to be acted on — read it before retrying.
The same operation elsewhere
This tool and the REST operation filesUpload and the CLI command inklate files upload run the same guarded procedure the dashboard uses — same permissions, same validation, same tenant isolation.