# 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

```http
POST /api/v1/files
```

```bash
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

```http
GET /api/v1/files
```

Required scope:

```text
files:read
```

```bash
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:

```json
{
  "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

```http
GET /api/v1/files/{fileId}
```

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

Response shape:

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

## Download file content

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

```bash
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:

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

Use `file_id` to retrieve metadata or download content.