Create a session

POST/v1/sessions

Create a reusable session for one enabled agent. A new session returns 201 Created. While that session is non-terminal, replaying the same idempotency_key with the same provisioning inputs returns it with 200 OK; the same key with different inputs returns 409 Conflict. Once the original session is stopped, failed, or expired, replay returns 412 Precondition Failed instead of creating a replacement.

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

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
agent_name	string	required	An agent enabled for the selected tenant.
idempotency_key	string	optional	Replays the same session for the same caller and request. At most 255 bytes.
model	string	optional	A model allowed by the deployed agent version.
agent_inputs	object	optional	Agent-specific initialization data.

Responses

Status	Meaning
200	An idempotent replay returned the existing non-terminal session.
201	The session was created.
409	The idempotency key matched a session created with different provisioning inputs.
412	The idempotency key refers to a session that is already terminal.

Request

cURL

Terminal

curl -X POST "https://api.tanomis.com/v1/sessions" \
  -H "Authorization: Bearer $TANOMIS_TOKEN" \
  -H "X-Organization-ID: $TANOMIS_ORG" \
  -H "X-Workspace-Tenant-ID: $TANOMIS_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "support-copilot",
    "idempotency_key": "support-case-1842"
  }'

Python

import httpx

response = httpx.post(
    f"https://api.tanomis.com/v1/sessions",
    headers={
        "Authorization": f"Bearer {token}",
        "X-Organization-ID": organization_id,
        "X-Workspace-Tenant-ID": tenant_id,
    },
    json={
        "agent_name": "support-copilot",
        "idempotency_key": "support-case-1842",
    },
)
response.raise_for_status()
result = response.json()

TypeScript

const response = await fetch(`https://api.tanomis.com/v1/sessions`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "X-Organization-ID": organizationId,
    "X-Workspace-Tenant-ID": tenantId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "agent_name": "support-copilot",
    "idempotency_key": "support-case-1842"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

Response

201 Created

{
  "id": "ses_7d4f9c",
  "agent_name": "support-copilot",
  "version": "0.4.0",
  "status": "ready",
  "model": "claude-sonnet",
  "created_at": "2026-09-02T11:42:18Z",
  "awaiting_input": false
}