Platform API

The application-facing HTTP surface for agents that are already deployed and enabled for the tenant selected by your workspace. Use it when your product or backend needs to invoke an agent directly. Routes used by the Tanomis control plane, an agent sandbox, or a platform operator are not part of this reference. For machine authentication, see Authenticate a backend. Human owner/admin operations for credentials and tenants are documented in the Organization management API.

Start with Sessions and runs when choosing an invocation boundary or designing retry and recovery behavior; return here for exact requests and responses. Use tanomis to author, deploy, and roll out agents.

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

Request basics

The hosted API origin is:

https://api.tanomis.com

Keep the origin free of a trailing /v1; every endpoint includes its own version prefix. For another Tanomis environment, use the API origin provided by its administrator.

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.

Authentication: a backend authenticates with an organization-owned automation client: exchange its client ID and secret for a short-lived token as described in Authenticate a backend. The CLI’s human login is not an application credential, and there is no separate token endpoint to guess from these examples.

Selecting a workspace projection supplies request context; the workspace does not own the tenant or its resources. A tenant header cannot widen a customer token. Do not use it to try to switch to a tenant the token does not grant.

Your first call

With a token in hand, three requests take you from nothing to a running agent:

1. Discover the workspace

GET /v1/me/workspaces
Authorization: Bearer <access-token>

2. Open a session

POST /v1/sessions
Authorization: Bearer <access-token>
X-Organization-ID: <organization_id>
X-Workspace-Tenant-ID: <tenant_id>

{ "agent_name": "support-copilot" }

3. Start a run and follow it

POST /v1/sessions/{session_id}/runs

{ "input": { "prompt": "Draft a reply to ticket 4821." }, "idempotency_key": "ticket-4821-1" }

GET /v1/sessions/{session_id}/runs/{run_id}/events

The walkthrough with responses is Invoke from your application.

Data conventions

• Request and response bodies are JSON unless an endpoint says otherwise.
• Unknown request fields are rejected instead of ignored.
• Resource IDs are opaque strings. Store them exactly as returned.
• Times use RFC 3339 UTC strings, such as 2026-09-02T11:42:18Z.
• Optional response fields may be absent. Clients should ignore response fields they do not know.

Endpoints

Workspaces

Method	Path	Operation
GET	/v1/whoami	Inspect the caller
GET	/v1/me/workspaces	List workspaces

Agents

Method	Path	Operation
GET	/v1/agents	List agents
POST	/v1/agents/{agent_name}/runs	Invoke once and stream

Sessions

Method	Path	Operation
POST	/v1/sessions	Create a session
GET	/v1/sessions	List sessions
GET	/v1/sessions/{session_id}	Read a session
POST	/v1/sessions/{session_id}/stop	Stop a session
POST	/v1/sessions/{session_id}/resume	Resume a session

Runs

Method	Path	Operation
POST	/v1/sessions/{session_id}/runs	Start a run
GET	/v1/sessions/{session_id}/runs	List runs
GET	/v1/sessions/{session_id}/runs/{run_id}	Read a run
GET	/v1/sessions/{session_id}/runs/{run_id}/events	Stream run events
POST	/v1/sessions/{session_id}/runs/{run_id}/cancel	Cancel a run

Interactions

Method	Path	Operation
GET	/v1/sessions/{session_id}/interactions	List interactions
POST	/v1/sessions/{session_id}/interactions/{interaction_key}/answer	Answer an interaction

Files

Method	Path	Operation
POST	/v1/sessions/{session_id}/files	Prepare a file
GET	/v1/sessions/{session_id}/files	List files
PUT	/v1/sessions/{session_id}/files/{file_id}/content	Upload file bytes
GET	/v1/sessions/{session_id}/files/{file_id}/content	Download file bytes
DELETE	/v1/sessions/{session_id}/files/{file_id}	Delete a file

Availability: Session-file endpoints appear only when file attachments are enabled for the environment. Read file_attachments_enabled from GET /v1/whoami, then session_files_supported on the session before showing those actions.

Complete request flow

This managed-workspace example creates a reusable session, starts one run, and follows its events. It requires curl and jq. Copy the organization and workspace selectors from GET /v1/me/workspaces:

Terminal

export TANOMIS_API="https://api.tanomis.com"
export TANOMIS_TOKEN="paste-a-short-lived-access-token"
export TANOMIS_ORG="org_abc123"
export TANOMIS_WORKSPACE="customer-production"

SESSION_ID="$(
  curl --silent --show-error --fail-with-body \\
    --request POST \\
    "$TANOMIS_API/v1/sessions" \\
    --header "Authorization: Bearer $TANOMIS_TOKEN" \\
    --header "X-Organization-ID: $TANOMIS_ORG" \\
    --header "X-Workspace-Tenant-ID: $TANOMIS_WORKSPACE" \\
    --header "Content-Type: application/json" \\
    --data '{"agent_name":"support-copilot","idempotency_key":"api-example-session-1"}' \\
  | jq --raw-output '.id'
)"

RUN_ID="$(
  curl --silent --show-error --fail-with-body \\
    --request POST \\
    "$TANOMIS_API/v1/sessions/$SESSION_ID/runs" \\
    --header "Authorization: Bearer $TANOMIS_TOKEN" \\
    --header "X-Organization-ID: $TANOMIS_ORG" \\
    --header "X-Workspace-Tenant-ID: $TANOMIS_WORKSPACE" \\
    --header "Content-Type: application/json" \\
    --data '{"input":{"prompt":"Summarize the open customer issue."},"idempotency_key":"api-example-run-1"}' \\
  | jq --raw-output '.id'
)"

curl --no-buffer --fail-with-body \\
  "$TANOMIS_API/v1/sessions/$SESSION_ID/runs/$RUN_ID/events" \\
  --header "Authorization: Bearer $TANOMIS_TOKEN" \\
  --header "X-Organization-ID: $TANOMIS_ORG" \\
  --header "X-Workspace-Tenant-ID: $TANOMIS_WORKSPACE" \\
  --header "Accept: text/event-stream"

When no more work will use the session, stop it with Stop a session.

Errors and retries

JSON errors include a machine-readable error code. Most application errors also include a human-readable message; clients must tolerate a code-only response from the access gate:

{
  "error": "invalid_status",
  "message": "unknown interaction status"
}

Status	Meaning	Client action
400	Invalid JSON, fields, selectors, or query parameters.	Fix the request; do not retry unchanged.
401	Missing, expired, or invalid access token.	Obtain a new token.
403	The caller does not have access to the selected organization/tenant projection or operation.	Change the grant or operation; do not retry unchanged.
404	The resource is absent in the selected tenant, or an optional capability is unavailable.	Check the selected workspace projection and resource id.
409	Lifecycle or idempotency conflict.	Read the returned or current resource before deciding whether to retry.
412	An idempotent create refers to a session that is already terminal.	Create a replacement with a new key if that is the intended action.
429	Request rate exceeded.	Retry with exponential backoff and jitter.
500–599	Temporary platform or upstream failure.	Retry boundedly with backoff.

Only retry a create or run request automatically when it carries the same idempotency_key and the same request body. For event streams, reconnect with Last-Event-ID instead of starting a new run.

Support boundary

The endpoints on this page are the supported application-invocation surface. Use the CLI for deployment and inspection and the Agent manifest for version configuration. Routes used by the Tanomis control plane, an agent sandbox, or a platform operator are intentionally not part of this customer reference.