Browse documentation

Files API

List runtime files, inspect metadata, and download artifacts.

The Files API exposes input and output artifacts associated with runtime execution.

Use files:write to upload input files. Use files:read to list, inspect, and download run files.

Upload an input file

POST /api/v1/files

curl "$SALAMBO_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $SALAMBO_API_KEY" \
  -H "Idempotency-Key: file-upload-001" \
  -F "file=@invoice.pdf"

The response contains a file_... identifier. Add that identifier to an input_file part when you start or continue a run.

List files

GET /api/v1/files

Required scope:

files:read

curl "$SALAMBO_BASE_URL/api/v1/files?run_id=run_...&limit=20" \
  -H "Authorization: Bearer $SALAMBO_API_KEY"

Query parameters:

Parameter	Type	Notes
`run_id`	string	Filter to files for a run.
`purpose`	string	Filter by file purpose.
`limit`	number	1-100, defaults to 20.
`after`	string	Cursor for pagination.

Response shape:

{
  "object": "list",
  "data": [
    {
      "id": "file_...",
      "object": "file",
      "bytes": 1234,
      "created_at": 1777473903,
      "filename": "report.md",
      "purpose": "output",
      "media_type": "text/markdown",
      "expires_at": null
    }
  ],
  "has_more": false,
  "first_id": "file_...",
  "last_id": "file_..."
}

Get file metadata

GET /api/v1/files/{fileId}

curl "$SALAMBO_BASE_URL/api/v1/files/file_..." \
  -H "Authorization: Bearer $SALAMBO_API_KEY"

Response shape:

{
  "id": "file_...",
  "object": "file",
  "bytes": 1234,
  "created_at": 1777473903,
  "expires_at": null,
  "filename": "report.md",
  "purpose": "output",
  "media_type": "text/markdown"
}

Download file content

GET /api/v1/files/{fileId}/content

curl "$SALAMBO_BASE_URL/api/v1/files/file_.../content" \
  -H "Authorization: Bearer $SALAMBO_API_KEY" \
  -L \
  -o artifact.bin

The endpoint returns a 302 redirect to a short-lived signed storage URL. Use -L with curl to follow the redirect.

Output file parts

Completed turns can contain output file parts:

{
  "type": "output_file",
  "file_id": "file_...",
  "filename": "report.md",
  "media_type": "text/markdown"
}

Use file_id to retrieve metadata or download content.

PreviousAgents and deployments API