# Attach files to a session

Give an agent documents to work on: prepare the file, upload its bytes, and reference it when you start a run.

A session can hold files that runs in that session read. Files are first-class resources with their
own ids, integrity checks, and lifecycle, so an upload is never a blind write into an agent's
workspace.

- Check `session_files_supported` on the session first.
- Prepare a file with its name, size, and `sha256`, upload the bytes, then reference its `file_id`
  in a run's `attachments`.
- Files belong to the session; list, download, and delete them there.

> **Availability:** Read `file_attachments_enabled` from [Inspect the caller](/api/workspaces/whoami), then `session_files_supported` on the session; the deployed version must also report file support. See [What is available where](/reference/availability).

## 1. Check support on the session

Create the session as usual, then read it. Continue only if `session_files_supported` is `true`.

## 2. Prepare the file

Declare the file before sending bytes, with its size and a SHA-256 digest of the content:

```json title="POST /v1/sessions/{session_id}/files"
{
  "filename": "case-summary.pdf",
  "media_type": "application/pdf",
  "size_bytes": 48213,
  "sha256": "83e0ef2f426dfad68f9b420304fc19414f8451a6bf24667f7e61c50e9ca57f14",
  "idempotency_key": "case-summary-v1"
}
```

The response carries the file's `id`, its `status` (`prepared`), and a `content_url`.

## 3. Upload the bytes

Send exactly `size_bytes` bytes to the content URL as `application/octet-stream`:

```bash title="Terminal"
curl -X PUT "$TANOMIS_API/v1/sessions/$SESSION_ID/files/$FILE_ID/content" \
  -H "Authorization: Bearer $TANOMIS_TOKEN" \
  -H "X-Organization-ID: $TANOMIS_ORG" \
  -H "X-Workspace-Tenant-ID: $TANOMIS_WORKSPACE" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @case-summary.pdf
```

The file becomes `ready` when the digest matches what you prepared. A size or digest mismatch is
refused rather than stored.

## 4. Reference it in a run

```json title="POST /v1/sessions/{session_id}/runs"
{
  "input": { "prompt": "Summarize the attached case." },
  "attachments": [{ "file_id": "file_b172c9" }],
  "idempotency_key": "case-summary-run-v1"
}
```

The agent sees the file in its session workspace. Files belong to the session: a run in another
session cannot reference them.

`GET /v1/sessions/{session_id}/files` lists the file with `"status": "ready"` before you start the
run. A `prepared` file that never became `ready` was not uploaded completely.

## Manage files

- **List**: `GET /v1/sessions/{session_id}/files`
- **Download**: `GET /v1/sessions/{session_id}/files/{file_id}/content`
- **Delete**: `DELETE /v1/sessions/{session_id}/files/{file_id}`

## Where to go next

- The endpoints with samples: [Prepare a file](/api/files/prepare-file) and the rest of the
  Files group in the [Platform API](/api).
- [Invoke from your application](/guides/run/invoke-from-your-application) for the surrounding
  session and run flow.