# API reference > Inspect the current OpenAPI routes and shared schemas. ## Conventions | | | | -------------- | --------------------------------------------------------- | | Base URL | `https://pantheon-todo.alethiconsulting.com/pantheon-api` | | Authentication | `Authorization: Bearer PANTHEON_API_KEY` | | JSON | Send `Content-Type: application/json`. | | Streaming | Request `text/event-stream`. | | Idempotency | Use an 8 to 255 character key where required. | ## Endpoints | Method | Path | Purpose | Success | Errors | | -------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------- | ------- | -------------------------------------- | | `post` | `/v1/auth/signup` | Signup | 201 | 422 | | `post` | `/v1/auth/login` | Login | 200 | 422 | | `post` | `/v1/auth/logout` | Logout | 204 | None | | `get` | `/v1/auth/me` | Me | 200 | None | | `get` | `/v1/auth/keys` | List Keys | 200 | None | | `post` | `/v1/auth/keys` | Create Key | 201 | 422 | | `delete` | `/v1/auth/keys/{key_id}` | Revoke Key | 204 | 422 | | `post` | `/v1/auth/password/change` | Change Password | 204 | 422 | | `post` | `/v1/auth/email/verify/request` | Request Verification | 202 | 401, 409, 429 | | `post` | `/v1/auth/email/verify/confirm` | Confirm Verification | 200 | 400, 422 | | `post` | `/v1/auth/password/reset/request` | Request Password Reset | 202 | 422, 429 | | `post` | `/v1/auth/password/reset/confirm` | Confirm Password Reset | 204 | 400, 422 | | `post` | `/v1/admin/users/{user_id}/password` | Admin Reset Password | 204 | 422 | | `get` | `/v1/admin/api-keys` | List Admin Api Keys | 200 | None | | `post` | `/v1/admin/api-keys` | Create Admin Api Key | 201 | 422 | | `delete` | `/v1/admin/api-keys/{key_id}` | Delete Admin Api Key | 204 | 422 | | `get` | `/v1/users/{user_id}/memory` | Get User Memory | 200 | 422 | | `delete` | `/v1/users/{user_id}/memory` | Delete User Memory | 200 | 422 | | `get` | `/v1/sessions/{session_id}/memory` | Get Session Memory | 200 | 422 | | `delete` | `/v1/sessions/{session_id}/memory` | Delete Session Memory | 200 | 422 | | `post` | `/v1/agents` | Create Agent | 201 | 422 | | `get` | `/v1/agents` | List Agents | 200 | 422 | | `get` | `/v1/agents/{agent_id}` | Get Agent | 200 | 422 | | `put` | `/v1/agents/{agent_id}` | Update Agent | 200 | 422 | | `delete` | `/v1/agents/{agent_id}` | Delete Agent | 204 | 422 | | `get` | `/v1/agents/slug/{slug}` | Get Agent By Slug | 200 | 422 | | `post` | `/v1/assistant/conversations` | Create Conversation | 201 | 401, 403, 404, 422, 503 | | `get` | `/v1/assistant/conversations` | List Conversations. Returns an object with data and next_page. | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/conversations/{conversation_id}` | Get Conversation | 200 | 400, 401, 403, 404, 422 | | `delete` | `/v1/assistant/conversations/{conversation_id}` | Delete Conversation | 204 | 401, 403, 404, 422, 503 | | `post` | `/v1/assistant/conversations/{conversation_id}/scope` | Switch Scope | 200 | 401, 403, 404, 409, 422, 503 | | `post` | `/v1/assistant/conversations/{conversation_id}/messages` | Message | 202 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/assistant/conversations/{conversation_id}/events` | List Events. Returns an object with data and next_cursor. | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/conversations/{conversation_id}/events/stream` | Stream | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/conversations/{conversation_id}/graphs/{graph_id}` | Graph | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/approvals` | List Approvals. Returns an object with data and next_page. | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/approvals/{approval_id}` | Get Approval | 200 | 400, 401, 403, 404, 422 | | `post` | `/v1/assistant/approvals/{approval_id}/decision` | Decide Approval | 200 | 401, 403, 404, 422, 503 | | `get` | `/v1/assistant/reply-evidence/{approval_id}` | Get Reply Evidence | 200 | 400, 401, 403, 404, 422 | | `post` | `/v1/assistant/reply-evidence/{approval_id}/decision` | Decide Reply Evidence | 200 | 401, 403, 404, 422, 503 | | `get` | `/v1/assistant/status` | Status | 200 | 400, 401, 403, 404, 422 | | `put` | `/v1/assistant/workspace-switch` | Workspace Switch | 200 | 401, 403, 404, 422 | | `get` | `/v1/assistant/preferences` | Preferences | 200 | 400, 401, 403, 404, 422 | | `patch` | `/v1/assistant/preferences` | Update Preferences | 200 | 401, 403, 404, 422, 503 | | `get` | `/v1/audit/records` | List Audit Records | 200 | 422 | | `post` | `/v1/deployments` | Create a deployment | 201 | 401, 403, 404, 422 | | `get` | `/v1/deployments` | List deployments. Returns an object with data and next_cursor. | 200 | 401, 403, 422 | | `get` | `/v1/deployments/{deployment_id}` | Get a deployment | 200 | 401, 403, 404, 422 | | `post` | `/v1/deployments/{deployment_id}/activate` | Activate Deployment | 200 | 404, 409, 422 | | `get` | `/v1/diagnostics/requests/{request_id}` | Request Lookup | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/agents/{agent_id}/observability` | Observability | 200 | 400, 401, 403, 404, 422 | | `post` | `/v1/admin/environments` | Create Environment | 201 | 422 | | `get` | `/v1/admin/environments` | List Environments Admin | 200 | 422 | | `get` | `/v1/admin/environments/{env_id}` | Get Environment Admin | 200 | 422 | | `put` | `/v1/admin/environments/{env_id}` | Update Environment | 200 | 422 | | `delete` | `/v1/admin/environments/{env_id}` | Delete Environment | 204 | 422 | | `get` | `/v1/environments` | List Environments | 200 | 422 | | `get` | `/v1/environments/{env_id}` | Get Environment | 200 | 422 | | `post` | `/v1/sessions/{session_id}/events` | Append session events | 200 | 401, 403, 404, 422, 429 | | `get` | `/v1/sessions/{session_id}/events` | List session events. Returns an object with data and next_cursor. | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/sessions/{session_id}/events/stream` | Stream session events | 200 | 400, 401, 403, 404, 422 | | `get` | `/health/components` | Component health | 200 | None | | `get` | `/v1/sessions/{session_id}/messages` | List Messages. Returns an object with data and next_page. | 200 | 422 | | `get` | `/v1/models` | List Models | 200 | None | | `post` | `/v1/sessions/{session_id}/runs/{run_id}/resume` | Resume a run | 202 | 400, 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/sessions/{session_id}/runs` | Start a run | 200 | 400, 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/sessions/{session_id}/runs/{run_id}/stream` | Stream run events | 200 | 401, 403, 404, 422 | | `post` | `/v1/sessions/{session_id}/runs/wait` | Start a run and wait | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/sessions/{session_id}/runs/{run_id}/stop` | Stop a run | 200 | 401, 403, 404, 422 | | `get` | `/v1/sessions/{session_id}/runs/{run_id}` | Get Run | 200 | 422 | | `post` | `/v1/sessions/{session_id}/runs/{run_id}/cancel` | Cancel a run | 202 | 401, 403, 404, 409, 422 | | `post` | `/v1/sessions/{session_id}/sandbox` | Provision Sandbox | 201 | 422 | | `delete` | `/v1/sessions/{session_id}/sandbox` | Destroy Sandbox | 204 | 422 | | `post` | `/v1/sessions/{session_id}/sandbox/sync` | Sync Sandbox | 200 | 422 | | `post` | `/v1/sessions/{session_id}/sandbox/extend-ttl` | Extend Sandbox Ttl | 200 | 422 | | `post` | `/v1/sessions/{session_id}/files/upload` | Upload File | 200 | 422 | | `get` | `/v1/sessions/{session_id}/files/{path}` | Download File | 200 | 422 | | `get` | `/v1/sessions/{session_id}/files` | List Files | 200 | 422 | | `get` | `/v1/secrets` | List Secrets | 200 | None | | `post` | `/v1/secrets` | Create Secret | 201 | 422 | | `get` | `/v1/secrets/{name}` | Get Secret | 200 | 422 | | `put` | `/v1/secrets/{name}` | Update Secret | 200 | 422 | | `delete` | `/v1/secrets/{name}` | Delete Secret | 204 | 422 | | `post` | `/v1/sessions` | Create Session | 201 | 422, 429 | | `get` | `/v1/sessions` | List Sessions. Returns an object with data and next_page. | 200 | 422 | | `get` | `/v1/sessions/{session_id}` | Get Session | 200 | 422 | | `post` | `/v1/sessions/{session_id}` | Update Session | 200 | 422 | | `delete` | `/v1/sessions/{session_id}` | Delete Session | 204 | 422 | | `post` | `/v1/sessions/{session_id}/archive` | Archive Session | 200 | 422 | | `get` | `/v1/skills` | List Tenant Skills | 200 | None | | `post` | `/v1/skills` | Create Tenant Skill | 201 | 422 | | `get` | `/v1/skills/{name}` | Get Tenant Skill | 200 | 422 | | `put` | `/v1/skills/{name}` | Update Tenant Skill | 200 | 422 | | `delete` | `/v1/skills/{name}` | Delete Tenant Skill | 204 | 422 | | `post` | `/v1/skills/import` | Import Tenant Skill Md | 201 | 422 | | `post` | `/v1/skills/validate` | Validate Skill | 200 | 422 | | `post` | `/v1/skills/upload` | Import Tenant Skill File | 201 | 422 | | `get` | `/v1/skills/{name}/download` | Download Tenant Skill | 200 | 422 | | `get` | `/v1/skills/{name}/files/content` | Get Tenant Skill File Content | 200 | 422 | | `post` | `/v1/skills/{name}/files` | Upload Tenant Skill File | 200 | 422 | | `post` | `/v1/admin/tenants/{tenant_id}/skills` | Create Org Skill | 201 | 422 | | `post` | `/v1/admin/skills/builtin` | Create Builtin Skill | 201 | 422 | | `get` | `/v1/sessions/{session_id}/skills/catalog` | Get Skill Catalog | 200 | 422 | | `put` | `/v1/sessions/{session_id}/skills/enabled` | Set Enabled Skills | 200 | 422 | | `get` | `/v1/sessions/{session_id}/artifacts` | List Artifacts | 200 | 422 | | `get` | `/v1/sessions/{session_id}/artifacts/{artifact_id}` | Get Artifact | 200 | 422 | | `delete` | `/v1/sessions/{session_id}/artifacts/{artifact_id}` | Delete Artifact | 200 | 422 | | `get` | `/v1/sessions/{session_id}/artifacts/{artifact_id}/download` | Download Artifact | 200 | 422 | | `get` | `/v1/sessions/{session_id}/artifacts/{artifact_id}/files/{path}` | Serve Artifact Subfile | 200 | 422 | | `get` | `/v1/api-keys` | List Tenant Api Keys | 200 | None | | `post` | `/v1/api-keys` | Create Tenant Api Key | 201 | 422 | | `delete` | `/v1/api-keys/{key_id}` | Delete Tenant Api Key | 204 | 422 | | `post` | `/v1/admin/tenants/{tenant_id}/api-keys` | Admin Create Tenant Api Key | 201 | 422 | | `get` | `/v1/admin/tenants/{tenant_id}/api-keys` | Admin List Tenant Api Keys | 200 | 422 | | `delete` | `/v1/admin/tenants/{tenant_id}/api-keys/{key_id}` | Admin Delete Tenant Api Key | 204 | 422 | | `post` | `/v1/users` | Create User | 201 | 422 | | `get` | `/v1/users` | List Users. Returns an object with data and next_page. | 200 | 422 | | `get` | `/v1/users/{user_id}` | Get User | 200 | 422 | | `put` | `/v1/users/{user_id}` | Update User | 200 | 422 | | `delete` | `/v1/users/{user_id}` | Delete User | 204 | 422 | | `get` | `/v1/admin/users` | Admin List Users. Returns an object with data and next_page. | 200 | 422 | | `get` | `/v1/admin/users/{user_id}` | Admin Get User | 200 | 422 | | `put` | `/v1/admin/users/{user_id}` | Admin Update User | 200 | 422 | | `post` | `/v1/admin/tenants` | Create Tenant | 201 | 422 | | `get` | `/v1/admin/tenants` | List Tenants | 200 | 422 | | `get` | `/v1/admin/tenants/{tenant_id}` | Get Tenant | 200 | 422 | | `put` | `/v1/admin/tenants/{tenant_id}` | Update Tenant | 200 | 422 | | `patch` | `/v1/admin/tenants/{tenant_id}` | Update Tenant | 200 | 422 | | `delete` | `/v1/admin/tenants/{tenant_id}` | Delete Tenant | 204 | 422 | | `get` | `/v1/workspace/receipts` | Workspace Receipts. Returns an object with data and next_cursor. | 200 | 422 | | `post` | `/v1/tests` | Create Test | 202 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/tests/{test_id}` | Get Test | 200 | 400, 401, 403, 404, 422 | | `post` | `/v1/tools` | Create a tool | 201 | 400, 401, 403, 409, 422 | | `get` | `/v1/tools` | List tools. Returns an object with data and next_cursor. | 200 | 401, 403, 422 | | `get` | `/v1/tools/{tool_id}` | Get tool by ID | 200 | 401, 403, 404, 422 | | `post` | `/v1/tools/{tool_id}/versions` | Create new tool definition version | 201 | 400, 401, 403, 404, 409, 422 | | `get` | `/v1/tools/{tool_id}/versions` | List tool definition versions. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 422 | | `get` | `/v1/tools/{tool_id}/versions/{version}` | Get specific tool definition version | 200 | 401, 403, 404, 422 | | `post` | `/v1/tools/{tool_id}/versions/{version}/deprecate` | Deprecate a tool definition version | 200 | 401, 403, 404, 422 | | `get` | `/v1/usage` | Get Usage | 200 | 422 | | `get` | `/v1/admin/tenants/{tenant_id}/usage` | Get Admin Usage | 200 | 422 | | `get` | `/v1/workspaces` | List Workspaces | 200 | 401, 422 | | `post` | `/v1/workspaces` | Create Workspace | 201 | 401, 409, 422, 429 | | `patch` | `/v1/workspaces/{workspace_id}` | Rename Workspace | 200 | 401, 403, 404, 409, 422 | | `delete` | `/v1/workspaces/{workspace_id}` | Delete Workspace | 200 | 401, 403, 404, 409, 422 | | `post` | `/v1/workspaces/{workspace_id}/restore` | Restore Workspace | 200 | 401, 403, 404, 409, 410, 422 | | `post` | `/v1/workspaces/{workspace_id}/switch` | Switch Workspace | 200 | 401, 404, 422 | | `get` | `/health` | Healthcheck | 200 | None | | `get` | `/` | Root Healthcheck | 200 | None | | `get` | `/v1/admin/bami/settings` | Settings | 200 | 401, 403, 404, 409, 422, 429, 503 | | `patch` | `/v1/admin/bami/settings` | Update Settings | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/tenants/{id}/settings` | Tenant Settings | 200 | 401, 403, 404, 409, 422, 429, 503 | | `patch` | `/v1/admin/bami/tenants/{id}/settings` | Update Tenant | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/kill` | Kill | 202 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/releases` | Releases. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/releases` | Release | 201 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/rollouts` | Rollout | 201 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/rollouts/{id}/rollback` | Rollback | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/metrics` | Metrics | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/audit` | Audit Records. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/support-access` | Support Access | 201 | 401, 403, 404, 409, 422, 429, 503 | | `delete` | `/v1/admin/bami/support-access/{id}` | Revoke Support | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/conversations/{id}` | Conversation | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/model` | Overview | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/model/qualifications` | Start Qualification | 202 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/model/qualifications/{id}` | Qualification | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/model/qualifications/{id}/enable` | Enable | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/auth/login` | Login | 202 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/auth/mfa` | Mfa | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/auth/session` | Session | 200 | 401, 403, 404, 409, 422, 429, 503 | | `delete` | `/v1/admin/bami/auth/session` | Logout | 204 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/containment-reviews` | Containment Reviews. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/console/containment-reviews/{review_id}` | Dispose Review | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/console/staff/{user_id}/emergency-revoke` | Emergency Revoke | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/operations/{idempotency_key}` | Operation | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/tenants` | Tenants. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/tenants/{tenant_id}` | Tenant Detail | 200 | 401, 403, 404, 409, 422, 429, 503 | | `patch` | `/v1/admin/console/tenants/{tenant_id}/classification` | Classify Tenant | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/usage` | Usage | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/usage/export` | Usage Export | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/audit` | Audit. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/console/tenants/{tenant_id}/suspend` | Suspend Tenant | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/console/tenants/{tenant_id}/resume` | Resume Tenant | 200 | 401, 403, 404, 409, 422, 429, 503 | | `patch` | `/v1/admin/console/tenants/{tenant_id}/limits` | Update Limits | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/tenants/{tenant_id}/keys` | Tenant Keys. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/console/tenants/{tenant_id}/keys/{key_id}/revoke` | Revoke Key | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/users` | Users. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/users/{user_id}` | User Detail | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/roles` | Roles. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `put` | `/v1/admin/console/roles/{user_id}` | Set Role | 200 | 401, 403, 404, 409, 422, 429, 503 | | `delete` | `/v1/admin/console/roles/{user_id}` | Revoke Role | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/console/approvals` | Create Approval | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/attention` | Attention. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/console/attention/{item_id}/acknowledge` | Acknowledge Attention | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/console/attention/{item_id}/resolve` | Resolve Attention | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/health` | Health | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/incidents` | Incidents. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/agents` | Agents. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/deployments` | Deployments. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/sessions` | Sessions. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/runs` | Runs. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/requests/{request_id}` | Request Correlation | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/notification-settings` | Notification Settings | 200 | 401, 403, 404, 409, 422, 429, 503 | | `patch` | `/v1/admin/console/notification-settings` | Update Notification Settings | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/console/data-requests` | Data Requests. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/console/data-requests` | Create Data Request | 200 | 401, 403, 404, 409, 422, 429, 503 | | `patch` | `/v1/admin/console/data-requests/{request_id}` | Update Data Request | 200 | 401, 403, 404, 409, 422, 429, 503 | ## Schemas The checked-in OpenAPI file is the field-level source of truth. | Schema | Required fields | Properties | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CreateToolRequest` | description, input_schema, output_schema, name, display_name | description, executor, input_schema, output_schema, side_effect, confirmation, name, display_name | | `CreateToolVersionRequest` | description, input_schema, output_schema | description, executor, input_schema, output_schema, side_effect, confirmation | | `ToolResponse` | id, name, display_name, latest_version, status, created_at, updated_at | id, name, display_name, latest_version, status, created_at, updated_at, latest_definition | | `ToolDefinitionResponse` | id, tool_id, name, version, description, executor, input_schema, output_schema, schema_profile_version, side_effect, confirmation, content_hash, status, created_at | id, tool_id, name, version, description, executor, input_schema, output_schema, schema_profile_version, side_effect, confirmation, content_hash, status, created_at | | `ToolListResponse` | data | data, next_cursor | | `CreateAgentRequest` | name, slug | name, slug, model, system_prompt, tools, tool_requirements, skills, environment_id, requires_sandbox, metadata | | `AgentResponse` | id, name, slug, model | id, name, slug, model, system_prompt, tools, tool_requirements, skills, environment_id, requires_sandbox, tool_policy, metadata, status, version, created_at, updated_at | | `CreateDeploymentRequest` | agent_id | agent_id, agent_version, tool_definition_ids, model, environment_id, application_tool_response_deadline_seconds | | `DeploymentResponse` | id, agent_id, agent_revision_id, agent_version, model, requires_sandbox, application_tool_response_deadline_seconds, prompt_policy_version, prompt_policy_hash, content_hash, source, status, active, created_at | id, agent_id, agent_revision_id, agent_version, model, environment_id, requires_sandbox, application_tool_response_deadline_seconds, prompt_policy_version, prompt_policy_hash, content_hash, source, status, active, tool_bindings, created_at | | `CreateSessionRequest` | None | agent_slug, deployment_id, prefer_latest_agent_version, user_id, environment_id, model, title, metadata, secrets, env | | `SessionResponse` | id, model | id, user_id, agent, agent_id, agent_slug, deployment, deployment_snapshot_id, deployment_source, environment_id, requires_sandbox, model, status, title, metadata, secrets, env, sandbox_id, sandbox_status, usage, created_at, updated_at, archived_at | | `CreateRunRequest` | None | events, model | | `RunResponse` | run_id, status | run_id, status, record_integrity, model_used, artifacts, required_event_ids | | `ResumeRequest` | events | events | | `ResumeAccepted` | run_id, status, accepted_events, remaining_event_ids | run_id, status, accepted_events, remaining_event_ids | | `EventResponse` | id, type | id, type, content, parent_event_id, run_id, model_used, seq, metadata, created_at, sequence, workspace_id, session_id, in_reply_to_event_id, data | | `ErrorEnvelope` | error | error | | `SessionBusyErrorEnvelope` | error | error | | `UsageResponse` | from, to, totals, daily | sandbox_seconds_estimated, from, to, totals, daily | | `UsageTotals` | None | sessions_created, runs_total, input_tokens, output_tokens, sandbox_seconds, tool_calls, runs_by_status | | `DailyUsage` | date | sessions_created, runs_total, input_tokens, output_tokens, sandbox_seconds, tool_calls, date | | `TenantRateLimitEnvelope` | error | error | | `TenantRateLimitDetails` | limit, window_seconds, retry_after | limit, window_seconds, retry_after | | `BamiConversation` | id, workspace_id, user_id, session_id, scope, scope_generation, title, active_run_id, release_id, model_version, created_at, updated_at, deleted_at, expires_at, cancellation_receipt_id, availability | id, workspace_id, user_id, session_id, scope, scope_generation, title, active_run_id, release_id, model_version, created_at, updated_at, deleted_at, expires_at, cancellation_receipt_id, availability | | `BamiReceipt` | id, kind, workspace_id, creator_id, conversation_id, request_id, session_id, run_id, via, label, outcome, reason, agent_id, agent_revision_id, agent_revision, deployment_id, deployment_hash, unavailable, effective_model, environment_id, prompt_policy_hash, executors, input, assertions, permitted_overrides, output_references, event_references, content_hashes, usage, remaining_local_change, proof_limits, usage_disclosed_at, created_at, completed_at, content_expires_at, content_deleted_at, audit_expires_at | id, kind, workspace_id, creator_id, conversation_id, request_id, session_id, run_id, via, label, outcome, reason, agent_id, agent_revision_id, agent_revision, deployment_id, deployment_hash, draft_id, draft_revision, draft_hash, test_snapshot_id, test_snapshot_hash, runtime_profile_version, unavailable, effective_model, environment_id, prompt_policy_hash, executors, input, assertions, permitted_overrides, output_references, event_references, content_hashes, usage, remaining_local_change, proof_limits, memory_isolated, usage_disclosed_at, created_at, completed_at, content_expires_at, content_deleted_at, audit_expires_at | | `BamiTestCreate` | deployment_id, title, input, assertions, executor_mode, tool_stubs | deployment_id, title, input, assertions, executor_mode, tool_stubs | | `BamiDiagnosticLookup` | target, audit, sessions, runs, events, coverage, next_cursors | target, audit, sessions, runs, events, coverage, next_cursors | ## Tool contracts | Value | Meaning | | ----------------- | ----------------------------------- | | `none` | Accepted for side_effect. Default. | | `workspace_write` | Accepted for side_effect. | | `external_write` | Accepted for side_effect. | | `never` | Accepted for confirmation. Default. | | `policy` | Accepted for confirmation. | Tool creation returns `ToolResponse`. Additional definition fields are omitted from this example. ```json title="Selected JSON response fields" { "id": "tool_123", "name": "echo_tool", "display_name": "Echo tool", "latest_version": 1, "status": "active", "created_at": "2026-09-08T12:00:00Z", "updated_at": "2026-09-08T12:00:00Z", "latest_definition": { "id": "tool_definition_123", "tool_id": "tool_123", "name": "echo_tool", "version": 1 } } ``` Deployments bind `latest_definition.id` through `tool_definition_ids`. Version requests accept only fields listed under `CreateToolVersionRequest` above. Sending `name` or `display_name` returns "Extra inputs are not permitted". See [Add a version](https://pantheon-todo.alethiconsulting.com/docs/application-tools#versions) for a request example. ## Bami routes Assistant, diagnostics, tests, and admin Bami routes are served by the integrated phase one API. The following 44 operations come from the same generated OpenAPI path set as the Endpoints table. Use a signed-in account session for assistant routes. Tenant and admin keys receive `SESSION_REQUIRED`. Admin Bami routes require a named MFA operator session; mutations require the dashboard Origin and CSRF token. Password and MFA exchanges establish that session. Admission remains disabled until a qualified release and operator settings enable it. Listing, reading and deletion remain available while disabled. Foundation component metadata records schema origin; operation paths establish route availability. | Method | Path | Purpose | Success | Errors | | -------- | ----------------------------------------------------------------- | -------------------------------------------------------------- | ------- | --------------------------------- | | `post` | `/v1/assistant/conversations` | Create Conversation | 201 | 401, 403, 404, 422, 503 | | `get` | `/v1/assistant/conversations` | List Conversations. Returns an object with data and next_page. | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/conversations/{conversation_id}` | Get Conversation | 200 | 400, 401, 403, 404, 422 | | `delete` | `/v1/assistant/conversations/{conversation_id}` | Delete Conversation | 204 | 401, 403, 404, 422, 503 | | `post` | `/v1/assistant/conversations/{conversation_id}/scope` | Switch Scope | 200 | 401, 403, 404, 409, 422, 503 | | `post` | `/v1/assistant/conversations/{conversation_id}/messages` | Message | 202 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/assistant/conversations/{conversation_id}/events` | List Events. Returns an object with data and next_cursor. | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/conversations/{conversation_id}/events/stream` | Stream | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/conversations/{conversation_id}/graphs/{graph_id}` | Graph | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/approvals` | List Approvals. Returns an object with data and next_page. | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/assistant/approvals/{approval_id}` | Get Approval | 200 | 400, 401, 403, 404, 422 | | `post` | `/v1/assistant/approvals/{approval_id}/decision` | Decide Approval | 200 | 401, 403, 404, 422, 503 | | `get` | `/v1/assistant/reply-evidence/{approval_id}` | Get Reply Evidence | 200 | 400, 401, 403, 404, 422 | | `post` | `/v1/assistant/reply-evidence/{approval_id}/decision` | Decide Reply Evidence | 200 | 401, 403, 404, 422, 503 | | `get` | `/v1/assistant/status` | Status | 200 | 400, 401, 403, 404, 422 | | `put` | `/v1/assistant/workspace-switch` | Workspace Switch | 200 | 401, 403, 404, 422 | | `get` | `/v1/assistant/preferences` | Preferences | 200 | 400, 401, 403, 404, 422 | | `patch` | `/v1/assistant/preferences` | Update Preferences | 200 | 401, 403, 404, 422, 503 | | `get` | `/v1/diagnostics/requests/{request_id}` | Request Lookup | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/agents/{agent_id}/observability` | Observability | 200 | 400, 401, 403, 404, 422 | | `post` | `/v1/tests` | Create Test | 202 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/tests/{test_id}` | Get Test | 200 | 400, 401, 403, 404, 422 | | `get` | `/v1/admin/bami/settings` | Settings | 200 | 401, 403, 404, 409, 422, 429, 503 | | `patch` | `/v1/admin/bami/settings` | Update Settings | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/tenants/{id}/settings` | Tenant Settings | 200 | 401, 403, 404, 409, 422, 429, 503 | | `patch` | `/v1/admin/bami/tenants/{id}/settings` | Update Tenant | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/kill` | Kill | 202 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/releases` | Releases. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/releases` | Release | 201 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/rollouts` | Rollout | 201 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/rollouts/{id}/rollback` | Rollback | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/metrics` | Metrics | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/audit` | Audit Records. Returns an object with data and next_cursor. | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/support-access` | Support Access | 201 | 401, 403, 404, 409, 422, 429, 503 | | `delete` | `/v1/admin/bami/support-access/{id}` | Revoke Support | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/conversations/{id}` | Conversation | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/model` | Overview | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/model/qualifications` | Start Qualification | 202 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/model/qualifications/{id}` | Qualification | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/model/qualifications/{id}/enable` | Enable | 200 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/auth/login` | Login | 202 | 401, 403, 404, 409, 422, 429, 503 | | `post` | `/v1/admin/bami/auth/mfa` | Mfa | 200 | 401, 403, 404, 409, 422, 429, 503 | | `get` | `/v1/admin/bami/auth/session` | Session | 200 | 401, 403, 404, 409, 422, 429, 503 | | `delete` | `/v1/admin/bami/auth/session` | Logout | 204 | 401, 403, 404, 409, 422, 429, 503 | See [Bami](https://pantheon-todo.alethiconsulting.com/docs/bami) for diagnose, correct, verify, and the phase one REST handoff. ## Use the contract Generate clients from [`api/openapi/openapi.json`](https://pantheon-todo.alethiconsulting.com/docs/openapi.json). Read [Get an API key](https://pantheon-todo.alethiconsulting.com/docs/get-a-key) for account setup and [Usage and limits](https://pantheon-todo.alethiconsulting.com/docs/usage) for tenant reporting. Use the [Quickstart](https://pantheon-todo.alethiconsulting.com/docs/quickstart) to test the generated client against a complete flow. ## Pitfalls > **Warning** > > - **New route examples are thin:** Read [Events](https://pantheon-todo.alethiconsulting.com/docs/events), [Errors](https://pantheon-todo.alethiconsulting.com/docs/errors), and [Sessions and runs](https://pantheon-todo.alethiconsulting.com/docs/sessions-and-runs). > - **Bami admission returns unavailable:** The routes are served, but admission requires enabled settings and a qualified release. Existing conversation reads remain available. > - **A schema changes:** Regenerate both SDKs from the same checked-in OpenAPI contract.