# Create a session

POST /v1/sessions: Create a reusable session for one enabled agent.

POST<code>/v1/sessions</code>

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](/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. |

## 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

```bash
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

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