Skip to main content
POST
Import uploaded file

Authorizations

Authorization
string
header
required

API token from cargo-ai login. Send as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was.

Maximum string length: 255
Example:

"8e03978e-40d5-43e8-bc93-6894a57f9324"

Body

application/json

Request body schema.

s3Filename
string
required

Key returned by the workspace multipart upload once it completed. Must belong to this workspace.

Minimum string length: 1
path
string
required

Where the file lives, /-separated, e.g. reports/2026-q3/summary.pdf. Missing folders are created; a file already at the path is overwritten.

Minimum string length: 1
contentType
string
required

MIME type of the file.

Minimum string length: 1
indexMode
enum<string>

none (default for a new file) only stores the bytes; vectorStore also sends them to OpenAI so agents can search them.

Available options:
none,
vectorStore
mirrorToContext
boolean

Also write the file under .files/ in the context repository. Defaults to false for a new file.

visibility
enum<string>

private (default) or public. A public file is served without auth from a stable link.

Available options:
private,
public

Response

Import uploaded file

file
File · object
required

The stored file.

path
string
required

The file's path.