Prepare a file

POST/v1/sessions/{session_id}/files

Prepare file metadata before uploading bytes. Check session_files_supported on the session first. The response carries an opaque id and a content_url; upload exactly size_bytes bytes there. File routes return 404 when attachments are disabled for the environment, and prepare and content transfer return 409 when this agent version lacks file support.

Generated from the Platform API specification on 2026-09-04.

Path parameters

Parameter	Type	Description
session_id	string	The session, as returned by Create a session.

Headers

Header	Required	Description
Authorization	yes	Bearer plus a short-lived OAuth access token issued for the Tanomis API audience. Backends obtain tokens with an organization automation client; the CLI’s human login is not an application credential.
X-Organization-ID	yes	The organization_id from the workspace projection you selected in GET /v1/me/workspaces.
X-Workspace-Tenant-ID	yes	The nested tenant_id from the same projection. A header cannot widen what the token grants. Some single-workspace or self-hosted environments take X-Tenant-ID instead, as supplied by their administrator.

Request body

Field	Type	Required	Description
filename	string	required
media_type	string	required
size_bytes	integer	required
sha256	string	required	Hex digest of the bytes you will upload.
idempotency_key	string	optional	Replays the same prepared file for the same request.

Responses

Status	Meaning
201	The prepared file.
404	File attachments are disabled for the environment, or no such session.
409	The deployed agent version does not support files.

Request

cURL

Terminal

curl -X POST "https://api.tanomis.com/v1/sessions/ses_7d4f9c/files" \
  -H "Authorization: Bearer $TANOMIS_TOKEN" \
  -H "X-Organization-ID: $TANOMIS_ORG" \
  -H "X-Workspace-Tenant-ID: $TANOMIS_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "case-summary.pdf",
    "media_type": "application/pdf",
    "size_bytes": 48213,
    "sha256": "83e0ef2f426dfad68f9b420304fc19414f8451a6bf24667f7e61c50e9ca57f14",
    "idempotency_key": "case-summary-v1"
  }'

Python

import httpx

response = httpx.post(
    f"https://api.tanomis.com/v1/sessions/{session_id}/files",
    headers={
        "Authorization": f"Bearer {token}",
        "X-Organization-ID": organization_id,
        "X-Workspace-Tenant-ID": tenant_id,
    },
    json={
        "filename": "case-summary.pdf",
        "media_type": "application/pdf",
        "size_bytes": 48213,
        "sha256": "83e0ef2f426dfad68f9b420304fc19414f8451a6bf24667f7e61c50e9ca57f14",
        "idempotency_key": "case-summary-v1",
    },
)
response.raise_for_status()
result = response.json()

TypeScript

const response = await fetch(`https://api.tanomis.com/v1/sessions/${sessionId}/files`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "X-Organization-ID": organizationId,
    "X-Workspace-Tenant-ID": tenantId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "filename": "case-summary.pdf",
    "media_type": "application/pdf",
    "size_bytes": 48213,
    "sha256": "83e0ef2f426dfad68f9b420304fc19414f8451a6bf24667f7e61c50e9ca57f14",
    "idempotency_key": "case-summary-v1"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

Response

201 Created

{
  "id": "file_b172c9",
  "filename": "case-summary.pdf",
  "media_type": "application/pdf",
  "size_bytes": 48213,
  "sha256": "83e0ef2f426dfad68f9b420304fc19414f8451a6bf24667f7e61c50e9ca57f14",
  "status": "prepared",
  "content_url": "https://api.tanomis.com/v1/sessions/ses_7d4f9c/files/file_b172c9/content",
  "created_at": "2026-09-02T11:45:00Z"
}