# Platform API

The application-facing HTTP surface for agents that are already deployed and enabled for the tenant selected by your workspace.

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](/guides/run/authenticate-your-backend). Human owner/admin operations for credentials and tenants are documented in the [Organization management API](/reference/organization-management-api).

Start with [Sessions and runs](/concepts/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:

```text
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](/guides/run/authenticate-your-backend); 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](/guides/deploy/automation-credentials): exchange its client ID and secret for a short-lived token as described in [Authenticate a backend](/guides/run/authenticate-your-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:

```text title="1. Discover the workspace"
GET /v1/me/workspaces
Authorization: Bearer <access-token>
```

```text title="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" }
```

```text title="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](/guides/run/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](/api/workspaces/whoami) |
| `GET` | `/v1/me/workspaces` | [List workspaces](/api/workspaces/list-workspaces) |

### Agents

| Method | Path | Operation |
|---|---|---|
| `GET` | `/v1/agents` | [List agents](/api/agents/list-agents) |
| `POST` | `/v1/agents/{agent_name}/runs` | [Invoke once and stream](/api/agents/invoke-agent) |

### Sessions

| Method | Path | Operation |
|---|---|---|
| `POST` | `/v1/sessions` | [Create a session](/api/sessions/create-session) |
| `GET` | `/v1/sessions` | [List sessions](/api/sessions/list-sessions) |
| `GET` | `/v1/sessions/{session_id}` | [Read a session](/api/sessions/get-session) |
| `POST` | `/v1/sessions/{session_id}/stop` | [Stop a session](/api/sessions/stop-session) |
| `POST` | `/v1/sessions/{session_id}/resume` | [Resume a session](/api/sessions/resume-session) |

### Runs

| Method | Path | Operation |
|---|---|---|
| `POST` | `/v1/sessions/{session_id}/runs` | [Start a run](/api/runs/start-run) |
| `GET` | `/v1/sessions/{session_id}/runs` | [List runs](/api/runs/list-runs) |
| `GET` | `/v1/sessions/{session_id}/runs/{run_id}` | [Read a run](/api/runs/get-run) |
| `GET` | `/v1/sessions/{session_id}/runs/{run_id}/events` | [Stream run events](/api/runs/stream-run-events) |
| `POST` | `/v1/sessions/{session_id}/runs/{run_id}/cancel` | [Cancel a run](/api/runs/cancel-run) |

### Interactions

| Method | Path | Operation |
|---|---|---|
| `GET` | `/v1/sessions/{session_id}/interactions` | [List interactions](/api/interactions/list-interactions) |
| `POST` | `/v1/sessions/{session_id}/interactions/{interaction_key}/answer` | [Answer an interaction](/api/interactions/answer-interaction) |

### Files

| Method | Path | Operation |
|---|---|---|
| `POST` | `/v1/sessions/{session_id}/files` | [Prepare a file](/api/files/prepare-file) |
| `GET` | `/v1/sessions/{session_id}/files` | [List files](/api/files/list-files) |
| `PUT` | `/v1/sessions/{session_id}/files/{file_id}/content` | [Upload file bytes](/api/files/upload-file-content) |
| `GET` | `/v1/sessions/{session_id}/files/{file_id}/content` | [Download file bytes](/api/files/download-file-content) |
| `DELETE` | `/v1/sessions/{session_id}/files/{file_id}` | [Delete a file](/api/files/delete-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`:

```bash title="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](/api/sessions/stop-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:

```json
{
  "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](/cli) for deployment and inspection and the [Agent manifest](/reference/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.