Skip to content
TanomisDocs
Open Console

Attach files to a session

1 min readUpdated

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.

Availability: Read file_attachments_enabled from Inspect the caller, then session_files_supported on the session; the deployed version must also report file support. See What is available where.

1. Check support on the session

Section titled “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

Section titled “2. Prepare the file”

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

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

Section titled “3. Upload the bytes”

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

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

Section titled “4. Reference it in a run”
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.

Manage files

Section titled “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

Section titled “Where to go next”