Skip to main content
POST
Upload file

Authorizations

Authorization
string
header
required

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

Body

application/json

Request body schema.

folderUuid
string<uuid>

Folder identifier to upload into.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
uuid
string<uuid>

When set, replace this file's content in place (keeping its uuid) instead of creating a new file. Ignored if no file with this uuid exists.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
indexMode
enum<string>

vectorStore (default for a new file) sends the file to OpenAI so agents can search it; none only stores the bytes. A replaced file keeps its own mode when unset.

Available options:
none,
vectorStore
visibility
enum<string>

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

Available options:
private,
public
mirrorToContext
enum<string>

Also write the file under .files/ in the context repository. Defaults to true for a new file; a replaced file keeps its own setting when unset.

Available options:
true,
false

Response

Upload file

files
Files · object[]
required

Uploaded files.