The Files API exposes input and output artifacts associated with runtime execution.
File endpoints accept either files:read or responses:write. Use files:read for integrations that only need to read artifacts.

​
List files

GET /api/v1/files
Required scope, either: 
files:read
responses:write

curl "$SALAMBO_BASE_URL/api/v1/files?response_id=resp_...&limit=20" \
  -H "Authorization: Bearer $SALAMBO_API_KEY"
Query parameters:
ParameterTypeNotes
response_idstringFilter to files for a response. Salambo resolves it to the backing run.
purposestringFilter by file purpose.
limitnumber1-100, defaults to 20.
afterstringCursor for pagination.
Response shape: 
{
  "object": "list",
  "data": [
    {
      "id": "file_...",
      "object": "file",
      "bytes": 1234,
      "created_at": 1777473903,
      "filename": "report.md",
      "purpose": "output",
      "mime_type": "text/markdown"
    }
  ],
  "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,
  "size_bytes": 1234,
  "created_at": 1777473903,
  "filename": "report.md",
  "purpose": "output",
  "mime_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 annotations

Response text can include file path annotations: 
{
  "type": "salambo:file_path",
  "file_id": "file_...",
  "path": "/workspace/output/report.md",
  "filename": "report.md"
}
Use file_id to retrieve metadata or download content.