Skip to main content
POST
Upload a file

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

X-Filename
string

The file's name, 1–255 characters with no control characters. Defaults to upload.<ext>, the extension chosen from Content-Type.

Required string length: 1 - 255
Idempotency-Key
string

1–255 printable ASCII characters. A repeat with the same key and the same bytes never stores the file again. It returns the first 201 (Idempotency-Replayed: true) while the caller still holds files:write and acts in the org tree the file was uploaded to; otherwise 409 idempotency_result_unavailable. Headers are not part of the request identity: a repeat with a different X-Filename or Content-Type returns the original result. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Query Parameters

scopeType
enum<string>

Bind the upload to this knowledge scope as well, as a Console upload is bound. The credential then also needs files:write at the scope's home: the named org unit for team, department and company; the factory's or project's home for factory and project; the deployment root for every other scope and for an org unit, factory or project that does not exist. A scope naming a top-level org unit or the deployment root also makes the file readable by credentials acting in that org tree. Without it, the upload is bound only to the credential's org unit, as before.

Available options:
personal,
team,
department,
company,
global,
factory,
project,
direct,
group,
system,
agent,
external_app,
customer,
organization
scopeEntityId
string

The scope's entity: the org unit, factory or project id. 1–255 characters with no control characters; needs scopeType.

Required string length: 1 - 255
source
enum<string>

Where the file came from, recorded on the scope binding. Defaults to api_upload; needs scopeType.

Available options:
chat_upload,
sandbox_import,
agent_output,
legacy_document,
api_upload

Body

The body is of type file.

Response

The stored file

data
object
required
meta
object
required