> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkato.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload a record file

> Upload a record file using an authenticated developer access key.

Required scopes: `records:write`.

Send multipart form data with `file` (required) and `parentId` (optional folder ID). Let your HTTP library set the multipart Content-Type boundary. `externalId` accepts 1–200 letters, digits, dots, underscores, colons or hyphens. Use a stable source ID: retries return the existing file, preserving user renames. Use a new ID for a new source version. Success returns `{ "data": { "id": "file-id" } }` plus file metadata. Workspace and pinned-record restrictions apply. Source bytes are stored privately; do not send an expiring source URL in place of the file.

See [authentication and rate limits](/api-reference/authentication).