> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Read accessible file metadata, download bytes, and upload files with durable operation status

All paths on this page are relative to `https://inkbox.ai/api/v1/slack`. File reads require an active identity and a connected workspace with access to the file.

## Get file metadata

```text theme={null}
GET /connections/{connection_id}/files/{file_id}
```

`connection_id` is a UUID. `file_id` starts with `F`, followed by uppercase letters or digits, up to 64 characters total. Get file IDs from message metadata or [file webhooks](/docs/api/slack/webhooks).

### Response (200)

```json theme={null}
{
  "id": "F0123456789",
  "name": "project-notes.txt",
  "title": "Project notes",
  "mimetype": "text/plain",
  "size": 2048,
  "downloadable": true
}
```

`name`, `title`, `mimetype`, and byte `size` can be `null`. `downloadable` indicates that Slack reports a supported file with a download location. It does not guarantee that the file will remain accessible or fit the download size limit.

## Download file content

```text theme={null}
GET /connections/{connection_id}/files/{file_id}/content
```

Returns `200` with raw file bytes and `Content-Type: application/octet-stream`. This is not JSON or a persistent file URL. The attachment filename uses the file ID.

```bash cURL theme={null}
curl "https://inkbox.ai/api/v1/slack/connections/22222222-2222-4222-8222-222222222222/files/F0123456789/content" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output project-notes.txt
```

Downloads are limited to 10 MiB. A larger file returns `413` with `detail.code: "file_too_large"`; retrying the same download will not bypass the limit. External files are unsupported and return `422`. An unavailable file can return `404`; another download failure can return `502`. Honor `Retry-After` on rate-limited reads.

Files are fetched live using the selected connection's permissions. Inkbox does not archive the bytes. Access may change after a file event arrives. File visibility does not prove the file's original workspace.

## Upload a file

```text theme={null}
POST /connections/{connection_id}/files
```

Requires `Idempotency-Key` and returns the [operation object](/docs/api/slack/operations#idempotent-operations), not a send action. The send-message endpoint still accepts text only.

| Field | Type | Required | Meaning |
| :- | :- | :- | :- |
| `conversation_id` | string | Yes | Destination conversation accessible to the bot |
| `filename` | string | Yes | Plain filename, `1`–`255` characters; no path separators or control characters |
| `content_base64` | string | Yes | Standard base64 encoding of `1` byte to `10` MiB of file content |
| `title` | string or null | No | Up to 255 characters |
| `initial_comment` | string or null | No | Up to 12,000 characters |
| `thread_ts` | string or null | No | Root timestamp when sharing into a thread |

```bash cURL theme={null}
curl -X POST "https://inkbox.ai/api/v1/slack/connections/22222222-2222-4222-8222-222222222222/files" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: project-notes-upload-01" \
  -d '{
    "conversation_id": "C0123456789",
    "filename": "notes.txt",
    "content_base64": "SGVsbG8=",
    "title": "Project notes"
  }'
```

The example uploads the five bytes `Hello`. Returns `200` with `operation: "file_upload"`. Inspect `status`; `file_id` can identify a file even when a later upload step fails or becomes uncertain. It is not proof the file was shared successfully.

An oversized request body returns `413`; invalid or oversized decoded file content returns `422`. Slack permissions, workspace upload policies, supported file types, and rate limits apply. A failed upload may have created a file before a later step failed. Keep the same key if the HTTP response is lost. For `unknown`, reconcile the file and conversation before deciding on a new upload; a new key can create a duplicate.

Inkbox does not retain the uploaded bytes as archive content. A later download still depends on current Slack access.