# Amika API — v0beta1 - **OpenAPI Version:** `3.1.0` - **API Version:** `v0beta1` ## Operations ### Send a message to a coding agent, creating a sandbox if needed - **Method:** `POST` - **Path:** `/agent-sessions` - **Tags:** AgentSessions #### Request Body ##### Content-Type: application/json - **`message` (required)** `string` - **`agent`** `string`, possible values: `"claude", "codex"` - **`branch`** `string` - **`effort`** `string | null`, possible values: `"low", "medium", "high", "xhigh", "max", null` - **`model`** `string | null`, possible values: `"fable", "opus", "sonnet", "haiku", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.2", null` - **`new_branch_name`** `string` - **`new_session`** `boolean` - **`repo_url`** `string` - **`sandbox_id`** `string` - **`session_id`** `string` **Example:** ```json { "message": "", "agent": "claude", "session_id": "", "sandbox_id": "", "new_session": true, "model": "fable", "effort": "low", "repo_url": "", "branch": "", "new_branch_name": "" } ``` #### Responses ##### Status: 200 Agent response. ###### Content-Type: application/json - **`agent` (required)** `string`, possible values: `"claude", "codex"` - **`created_sandbox` (required)** `boolean` - **`is_error` (required)** `boolean` — True when the turn failed. The failure is still a 200: \`response\` carries the agent CLI's own message (e.g. "Not logged in · Please run /login"). - **`is_new_session` (required)** `boolean` - **`response` (required)** `string` - **`sandbox_id` (required)** `string` - **`session_id` (required)** `string` - **`usage`** `object` - **`cache_creation_tokens`** `integer` - **`cache_read_tokens`** `integer` - **`cost_usd`** `number` - **`duration_ms`** `integer` - **`input_tokens`** `integer` - **`num_turns`** `integer` - **`output_tokens`** `integer` **Example:** ```json { "session_id": "", "sandbox_id": "", "agent": "claude", "response": "", "is_error": true, "is_new_session": true, "created_sandbox": true, "usage": { "cost_usd": 1, "input_tokens": 0, "output_tokens": 0, "cache_read_tokens": 0, "cache_creation_tokens": 0, "duration_ms": 0, "num_turns": 0 } } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List the org's agent-session chats - **Method:** `GET` - **Path:** `/agent-sessions` - **Tags:** AgentSessions #### Parameters ##### `limit` - **In:** `query` `integer` ##### `offset` - **In:** `query` `[ "integer", "null" ]` #### Responses ##### Status: 200 Agent-session chats, newest first. ###### Content-Type: application/json - **`sessions` (required)** `array` **Items:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` - **`total` (required)** `integer` **Example:** ```json { "sessions": [ { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "" } ], "total": 0 } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Send a message to a coding agent, streaming the reply (SSE) - **Method:** `POST` - **Path:** `/agent-sessions/stream` - **Tags:** AgentSessions #### Request Body ##### Content-Type: application/json - **`message` (required)** `string` - **`agent`** `string`, possible values: `"claude", "codex"` - **`branch`** `string` - **`effort`** `string | null`, possible values: `"low", "medium", "high", "xhigh", "max", null` - **`model`** `string | null`, possible values: `"fable", "opus", "sonnet", "haiku", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.2", null` - **`new_branch_name`** `string` - **`new_session`** `boolean` - **`repo_url`** `string` - **`sandbox_id`** `string` - **`session_id`** `string` **Example:** ```json { "message": "", "agent": "claude", "session_id": "", "sandbox_id": "", "new_session": true, "model": "fable", "effort": "low", "repo_url": "", "branch": "", "new_branch_name": "" } ``` #### Responses ##### Status: 200 A \`text/event-stream\` of the send. Frames are named by the SSE \`event:\` field: \`status\`, \`delta\`, terminal \`done\` (the full \`AgentSessionSendResponse\`), or \`error\`. ###### Content-Type: text/event-stream **Any of:** - **`phase` (required)** `string`, possible values: `"creating_sandbox", "sandbox_ready"` - **`sandbox_id`** `string` * **`text` (required)** `string` - **`agent` (required)** `string`, possible values: `"claude", "codex"` - **`created_sandbox` (required)** `boolean` - **`is_error` (required)** `boolean` — True when the turn failed. The failure is still a 200: \`response\` carries the agent CLI's own message (e.g. "Not logged in · Please run /login"). - **`is_new_session` (required)** `boolean` - **`response` (required)** `string` - **`sandbox_id` (required)** `string` - **`session_id` (required)** `string` - **`usage`** `object` - **`cache_creation_tokens`** `integer` - **`cache_read_tokens`** `integer` - **`cost_usd`** `number` - **`duration_ms`** `integer` - **`input_tokens`** `integer` - **`num_turns`** `integer` - **`output_tokens`** `integer` * **`error` (required)** `string` **Example:** ```json { "phase": "creating_sandbox", "sandbox_id": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read an agent session - **Method:** `GET` - **Path:** `/agent-sessions/{id}` - **Tags:** AgentSessions #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Agent session. ###### Content-Type: application/json **All of:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`messages` (required)** `array` **Items:** - **`content` (required)** `string` - **`role` (required)** `string` - **`timestamp` (required)** `string` - **`is_error`** `boolean` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "", "messages": [ { "role": "", "content": "", "timestamp": "", "is_error": true } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Stream a session's events (SSE) - **Method:** `GET` - **Path:** `/agent-sessions/{id}/events` - **Tags:** AgentSessions #### Parameters ##### `id` required - **In:** `path` `string` ##### `after_seq` - **In:** `query` `string` ##### `max_ms` - **In:** `query` `string` ##### `follow` - **In:** `query` `string`, possible values: `"0", "1", "true", "false", "yes", "no"` ##### `include_raw` - **In:** `query` `string`, possible values: `"0", "1", "true", "false"` #### Responses ##### Status: 200 A \`text/event-stream\` of the session's events. Each event frame's \`id\` is the event \`seq\` (a resume cursor); \`event\` is the kind. Control frames \`done\`/\`timeout\`/\`heartbeat\`/\`error\` are also sent. ###### Content-Type: text/event-stream - **`created_at` (required)** `object` - **`id` (required)** `string` - **`kind` (required)** `string` - **`payload` (required)** `object` - **`seq` (required)** `integer` **Example:** ```json { "seq": 0, "id": "", "kind": "", "payload": {}, "created_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List API keys - **Method:** `GET` - **Path:** `/api-keys` - **Tags:** API keys #### Parameters ##### `scope` - **In:** `query` Restrict the listing to a single scope. Omit to list both organization- and user-scoped keys merged together. `string`, possible values: `"organization", "user"` — Restrict the listing to a single scope. Omit to list both organization- and user-scoped keys merged together. ##### `after` - **In:** `query` Pagination cursor returned by a previous list call. `string` — Pagination cursor returned by a previous list call. ##### `limit` - **In:** `query` Maximum number of API keys to return. `integer` — Maximum number of API keys to return. #### Responses ##### Status: 200 Page of API keys visible to the caller: organization-scoped keys for their org plus user-scoped keys they own, unless narrowed with \`scope\`. ###### Content-Type: application/json - **`data` (required)** `array` **Items:** - **`createdAt` (required)** `string` - **`id` (required)** `string` - **`lastUsedAt` (required)** `string | null` - **`name` (required)** `string` - **`obfuscatedValue` (required)** `string` - **`scope` (required)** `string`, possible values: `"organization", "user"` — Whether the key is scoped to the caller's organization or to the individual user who owns it. - **`updatedAt` (required)** `string` - **`pageInfo` (required)** `object` - **`after` (required)** `string | null` - **`hasNextPage` (required)** `boolean` **Example:** ```json { "data": [ { "id": "", "name": "", "scope": "organization", "obfuscatedValue": "", "lastUsedAt": null, "createdAt": "", "updatedAt": "" } ], "pageInfo": { "after": null, "hasNextPage": true } } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create an API key - **Method:** `POST` - **Path:** `/api-keys` - **Tags:** API keys #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — Human-readable name for the API key. - **`scope`** `string`, possible values: `"organization", "user"`, default: `"organization"` — Scope of the key to create. Defaults to \`organization\`; pass \`user\` to mint a key owned by the calling user. **Example:** ```json { "name": "", "scope": "organization" } ``` #### Responses ##### Status: 201 Created API key, including its plaintext value. ###### Content-Type: application/json **All of:** - **`createdAt` (required)** `string` - **`id` (required)** `string` - **`lastUsedAt` (required)** `string | null` - **`name` (required)** `string` - **`obfuscatedValue` (required)** `string` - **`scope` (required)** `string`, possible values: `"organization", "user"` — Whether the key is scoped to the caller's organization or to the individual user who owns it. - **`updatedAt` (required)** `string` * **`value` (required)** `string` **Example:** ```json { "id": "", "name": "", "scope": "organization", "obfuscatedValue": "", "lastUsedAt": null, "createdAt": "", "updatedAt": "", "value": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete an API key - **Method:** `DELETE` - **Path:** `/api-keys/{id}` - **Tags:** API keys #### Parameters ##### `id` required - **In:** `path` WorkOS API key id. `string` — WorkOS API key id. ##### `scope` - **In:** `query` Scope of the key to delete. Defaults to `organization`; pass `user` to revoke a user-scoped key. `string`, possible values: `"organization", "user"`, default: `"organization"` — Scope of the key to delete. Defaults to \`organization\`; pass \`user\` to revoke a user-scoped key. #### Responses ##### Status: 204 API key deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List the org's docker registries - **Method:** `GET` - **Path:** `/docker-registries` - **Tags:** Docker registries #### Responses ##### Status: 200 Array of docker registries owned by the caller's org. ###### Content-Type: application/json **Array of:** - **`created_at` (required)** `object` - **`daytona_registry_id` (required)** `string` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`updated_at` (required)** `object` - **`url` (required)** `string` - **`registry_type`** `string | null` - **`username`** `string | null` **Example:** ```json [ { "id": "", "org_id": "", "name": "", "url": "", "daytona_registry_id": "", "created_at": "", "updated_at": "", "username": null, "registry_type": null } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Register a docker registry - **Method:** `POST` - **Path:** `/docker-registries` - **Tags:** Docker registries #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`password` (required)** `string` - **`url` (required)** `string` - **`username` (required)** `string` - **`project`** `string` **Example:** ```json { "name": "", "url": "", "username": "", "password": "", "project": "" } ``` #### Responses ##### Status: 201 Created docker registry row. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`daytona_registry_id` (required)** `string` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`updated_at` (required)** `object` - **`url` (required)** `string` - **`registry_type`** `string | null` - **`username`** `string | null` **Example:** ```json { "id": "", "org_id": "", "name": "", "url": "", "daytona_registry_id": "", "created_at": "", "updated_at": "", "username": null, "registry_type": null } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a docker registry - **Method:** `DELETE` - **Path:** `/docker-registries/{id}` - **Tags:** Docker registries #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 Deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read the caller's git user settings - **Method:** `GET` - **Path:** `/git-user-settings` - **Tags:** Git user settings #### Responses ##### Status: 200 Configured git user settings, or a suggestion derived from the WorkOS profile when none are saved. ###### Content-Type: application/json **Any of:** - **`configured` (required)** `boolean`, possible values: `true` - **`email` (required)** `string` - **`name` (required)** `string` - **`suggestion` (required)** `object` - **`email` (required)** `string` - **`name` (required)** `string` * **`configured` (required)** `boolean`, possible values: `false` * **`suggestion` (required)** `object` - **`email` (required)** `string` - **`name` (required)** `string` **Example:** ```json { "configured": true, "name": "", "email": "", "suggestion": { "name": "", "email": "" } } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create or update the caller's git user settings - **Method:** `POST` - **Path:** `/git-user-settings` - **Tags:** Git user settings #### Request Body ##### Content-Type: application/json - **`email` (required)** `string` - **`name` (required)** `string` **Example:** ```json { "name": "", "email": "" } ``` #### Responses ##### Status: 201 Updated row. ###### Content-Type: application/json - **`created_at` (required)** `string` - **`email` (required)** `string` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`updated_at` (required)** `string` - **`user_id` (required)** `string` **Example:** ```json { "id": "", "org_id": "", "user_id": "", "name": "", "email": "", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List the organization's hosts - **Method:** `GET` - **Path:** `/hosts` - **Tags:** Hosts #### Responses ##### Status: 200 Hosts in the caller's organization. ###### Content-Type: application/json **Array of:** - **`created_at` (required)** `object` - **`hostname` (required)** `string` - **`id` (required)** `string` - **`org_id` (required)** `string` - **`sizes` (required)** `object` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` **Example:** ```json [ { "id": "", "hostname": "", "url": null, "org_id": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } }, "created_at": "", "updated_at": "" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Register an organization host - **Method:** `POST` - **Path:** `/hosts` - **Tags:** Hosts Idempotent by hostname: registering a hostname the organization already has returns that host with 200 and leaves its stored secret and sizes unchanged. Use PUT to rotate the secret or replace the sizes. #### Request Body ##### Content-Type: application/json - **`hostname` (required)** `string` - **`secret` (required)** `string` - **`sizes`** `object` - **`url`** `string | null`, format: `uri` **Example:** ```json { "hostname": "", "url": null, "secret": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } } } ``` #### Responses ##### Status: 200 Host already registered. The secret value is never returned. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`hostname` (required)** `string` - **`id` (required)** `string` - **`org_id` (required)** `string` - **`sizes` (required)** `object` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` **Example:** ```json { "id": "", "hostname": "", "url": null, "org_id": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } }, "created_at": "", "updated_at": "" } ``` ##### Status: 201 Created host. The secret value is never returned. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`hostname` (required)** `string` - **`id` (required)** `string` - **`org_id` (required)** `string` - **`sizes` (required)** `object` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` **Example:** ```json { "id": "", "hostname": "", "url": null, "org_id": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } }, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Get an organization host - **Method:** `GET` - **Path:** `/hosts/{id}` - **Tags:** Hosts #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Host metadata. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`hostname` (required)** `string` - **`id` (required)** `string` - **`org_id` (required)** `string` - **`sizes` (required)** `object` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` **Example:** ```json { "id": "", "hostname": "", "url": null, "org_id": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } }, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Replace an organization host - **Method:** `PUT` - **Path:** `/hosts/{id}` - **Tags:** Hosts hostname is required. Omit secret to keep the stored credential; omit url to keep the stored URL, or send it as null to clear it; omit sizes to keep the stored sizes, or send {} to clear them. #### Parameters ##### `id` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`hostname` (required)** `string` - **`secret`** `string` - **`sizes`** `object` - **`url`** `string | null`, format: `uri` **Example:** ```json { "hostname": "", "url": null, "secret": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } } } ``` #### Responses ##### Status: 200 Updated host. The secret value is never returned. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`hostname` (required)** `string` - **`id` (required)** `string` - **`org_id` (required)** `string` - **`sizes` (required)** `object` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` **Example:** ```json { "id": "", "hostname": "", "url": null, "org_id": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } }, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete an organization host and its stored secret - **Method:** `DELETE` - **Path:** `/hosts/{id}` - **Tags:** Hosts Refused with 409 while any rig still runs on the host. #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 Host deleted. ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Reveal an organization host's secret - **Method:** `POST` - **Path:** `/hosts/{id}/reveal` - **Tags:** Hosts Only a signed-in user can reveal a host's secret; an API key or other service identity is refused with 403. A POST rather than a GET so the value is never cached or prefetched. #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 The host's secret. ###### Content-Type: application/json - **`value` (required)** `string` **Example:** ```json { "value": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List the caller's connected integrations - **Method:** `GET` - **Path:** `/integrations/credentials` - **Tags:** Integrations #### Responses ##### Status: 200 Connected integration providers. ###### Content-Type: application/json **Array of:** - **`connected` (required)** `boolean` - **`provider` (required)** `string` **Example:** ```json [ { "provider": "", "connected": true } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Disconnect an integration provider for the caller - **Method:** `DELETE` - **Path:** `/integrations/{provider}/credentials` - **Tags:** Integrations #### Parameters ##### `provider` required - **In:** `path` `string` #### Responses ##### Status: 204 Disconnected. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List the org's repositories - **Method:** `GET` - **Path:** `/repositories` - **Tags:** Repositories #### Responses ##### Status: 200 Array of repositories. ###### Content-Type: application/json **Array of:** - **`created_at` (required)** `object` - **`default_snapshot` (required)** `string | null` - **`id` (required)** `string` - **`org_id` (required)** `string` - **`repo_url` (required)** `string` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`setup_script` (required)** `string | null` - **`start_script` (required)** `string | null` - **`updated_at` (required)** `object` - **`user_id` (required)** `string | null` **Example:** ```json [ { "id": "", "org_id": "", "user_id": null, "repo_url": "", "setup_script": null, "start_script": null, "sandbox_preset": null, "sandbox_size": null, "default_snapshot": null, "created_at": "", "updated_at": "" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create or update a repository - **Method:** `POST` - **Path:** `/repositories` - **Tags:** Repositories #### Request Body ##### Content-Type: application/json - **`repo_url` (required)** `string` - **`default_snapshot`** `string | null` - **`sandbox_preset`** `string | null` - **`sandbox_size`** `string | null` - **`setup_script`** `string` - **`start_script`** `string` **Example:** ```json { "repo_url": "", "setup_script": "", "start_script": "", "sandbox_preset": null, "sandbox_size": null, "default_snapshot": null } ``` #### Responses ##### Status: 201 Created or upserted repository. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`default_snapshot` (required)** `string | null` - **`id` (required)** `string` - **`org_id` (required)** `string` - **`repo_url` (required)** `string` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`setup_script` (required)** `string | null` - **`start_script` (required)** `string | null` - **`updated_at` (required)** `object` - **`user_id` (required)** `string | null` **Example:** ```json { "id": "", "org_id": "", "user_id": null, "repo_url": "", "setup_script": null, "start_script": null, "sandbox_preset": null, "sandbox_size": null, "default_snapshot": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read a single repository - **Method:** `GET` - **Path:** `/repositories/{id}` - **Tags:** Repositories #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Repository. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`default_snapshot` (required)** `string | null` - **`id` (required)** `string` - **`org_id` (required)** `string` - **`repo_url` (required)** `string` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`setup_script` (required)** `string | null` - **`start_script` (required)** `string | null` - **`updated_at` (required)** `object` - **`user_id` (required)** `string | null` **Example:** ```json { "id": "", "org_id": "", "user_id": null, "repo_url": "", "setup_script": null, "start_script": null, "sandbox_preset": null, "sandbox_size": null, "default_snapshot": null, "created_at": "", "updated_at": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Clear repository image config - **Method:** `DELETE` - **Path:** `/repositories/{id}/image` - **Tags:** Repositories #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 Cleared. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List a repository's MCP integrations - **Method:** `GET` - **Path:** `/repositories/{id}/integrations` - **Tags:** Repositories #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Integrations. ###### Content-Type: application/json **Array of:** - **`created_at` (required)** `object` - **`id` (required)** `string` - **`mcp_server_type` (required)** `string` - **`mcp_server_url` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`repository_id` (required)** `string` - **`updated_at` (required)** `object` **Example:** ```json [ { "id": "", "repository_id": "", "org_id": "", "name": "", "mcp_server_type": "", "mcp_server_url": "", "created_at": "", "updated_at": "" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Replace a repository's MCP integrations - **Method:** `PUT` - **Path:** `/repositories/{id}/integrations` - **Tags:** Repositories #### Parameters ##### `id` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`integrations` (required)** `array` **Items:** **One of:** - **`mcp_server_type` (required)** `string`, possible values: `"http"` - **`mcp_server_url` (required)** `string`, format: `uri` - **`name` (required)** `string` * **`mcp_server_type` (required)** `string`, possible values: `"stdio"` * **`name` (required)** `string`, possible values: `"playwright"` * **`mcp_server_url`** `string`, default: `""` **Example:** ```json { "integrations": [ { "name": "", "mcp_server_type": "http", "mcp_server_url": "" } ] } ``` #### Responses ##### Status: 200 Updated integrations. ###### Content-Type: application/json **Array of:** - **`created_at` (required)** `object` - **`id` (required)** `string` - **`mcp_server_type` (required)** `string` - **`mcp_server_url` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`repository_id` (required)** `string` - **`updated_at` (required)** `object` **Example:** ```json [ { "id": "", "repository_id": "", "org_id": "", "name": "", "mcp_server_type": "", "mcp_server_url": "", "created_at": "", "updated_at": "" } ] ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read a repository's workflow - **Method:** `GET` - **Path:** `/repositories/{id}/workflow` - **Tags:** Repositories #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Workflow (or null when none configured). ###### Content-Type: application/json - **`workflow` (required)** `object` - **`created_at` (required)** `object` - **`default_agent` (required)** `string | null` - **`start_step` (required)** `string` - **`steps` (required)** `array` **Items:** - **`body` (required)** `string` - **`name` (required)** `string` - **`on_failure` (required)** `string | null` - **`on_success` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "workflow": { "default_agent": null, "start_step": "", "steps": [ { "name": "", "body": "", "on_success": null, "on_failure": null } ], "created_at": "", "updated_at": "" } } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Replace a repository's workflow - **Method:** `PUT` - **Path:** `/repositories/{id}/workflow` - **Tags:** Repositories #### Parameters ##### `id` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`start_step` (required)** `string` - **`steps` (required)** `array` **Items:** - **`body` (required)** `string` - **`name` (required)** `string` - **`on_failure`** `string | null` - **`on_success`** `string | null` - **`default_agent`** `string | null`, possible values: `"claude", "codex", null` **Example:** ```json { "default_agent": "claude", "start_step": "", "steps": [ { "name": "", "body": "", "on_success": null, "on_failure": null } ] } ``` #### Responses ##### Status: 200 Updated workflow. ###### Content-Type: application/json - **`workflow` (required)** `object` - **`created_at` (required)** `object` - **`default_agent` (required)** `string | null` - **`start_step` (required)** `string` - **`steps` (required)** `array` **Items:** - **`body` (required)** `string` - **`name` (required)** `string` - **`on_failure` (required)** `string | null` - **`on_success` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "workflow": { "default_agent": null, "start_step": "", "steps": [ { "name": "", "body": "", "on_success": null, "on_failure": null } ], "created_at": "", "updated_at": "" } } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Clear a repository's workflow - **Method:** `DELETE` - **Path:** `/repositories/{id}/workflow` - **Tags:** Repositories #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 Cleared. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List sandbox bindings for the caller's organization - **Method:** `GET` - **Path:** `/sandbox-bindings` - **Tags:** SandboxBindings #### Responses ##### Status: 200 Bindings. ###### Content-Type: application/json - **`items` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`created_by_id` (required)** `string` - **`created_by_kind` (required)** `string`, possible values: `"user", "system"` - **`id` (required)** `string` - **`metadata` (required)** `object` - **`relationship` (required)** `string` - **`sandbox_id` (required)** `string` - **`system_metadata` (required)** `object` - **`target_id` (required)** `string` - **`target_kind` (required)** `string` - **`target_namespace` (required)** `string` - **`target_url` (required)** `string`, format: `uri` - **`updated_at` (required)** `object` **Example:** ```json { "items": [ { "id": "", "sandbox_id": "", "target_namespace": "", "target_kind": "", "target_id": "", "target_url": "", "relationship": "", "metadata": {}, "system_metadata": {}, "created_by_kind": "user", "created_by_id": "", "created_at": "", "updated_at": "" } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a sandbox binding - **Method:** `DELETE` - **Path:** `/sandbox-bindings/{id}` - **Tags:** SandboxBindings #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 Deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List live sandbox services for the caller's org - **Method:** `GET` - **Path:** `/sandbox-services` - **Tags:** SandboxServices #### Parameters ##### `sandbox_id` - **In:** `query` Only this sandbox's services, by sandbox id. `string` — Only this sandbox's services, by sandbox id. ##### `sandbox_name` - **In:** `query` Only this sandbox's services, by sandbox name. `string` — Only this sandbox's services, by sandbox name. ##### `sandbox_ref` - **In:** `query` Only this sandbox's services, by id or name (rejected if both match). `string` — Only this sandbox's services, by id or name (rejected if both match). #### Responses ##### Status: 200 Services. ###### Content-Type: application/json - **`items` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`host_port` (required)** `integer | null` - **`id` (required)** `string | null` - **`kind` (required)** `string`, possible values: `"system", "user"` - **`name` (required)** `string` - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`sandbox_id` (required)** `string` - **`source` (required)** `string`, possible values: `"table", "legacy"` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` - **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "items": [ { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List sandbox-captured snapshots for the caller's org - **Method:** `GET` - **Path:** `/sandbox-snapshots` - **Tags:** SandboxSnapshots #### Parameters ##### `repository_id` - **In:** `query` If set, only return snapshots taken from sandboxes attached to this repository. `string` — If set, only return snapshots taken from sandboxes attached to this repository. ##### `source_sandbox_id` - **In:** `query` If set, only return snapshots captured from this sandbox. `string` — If set, only return snapshots captured from this sandbox. #### Responses ##### Status: 200 Snapshots. ###### Content-Type: application/json - **`items` (required)** `array` **Items:** - **`base_snapshot` (required)** `string | null` - **`capture_mode` (required)** `string | null` - **`created_at` (required)** `object` - **`daytona` (required)** `object` - **`name` (required)** `string` - **`cpu`** `number` - **`createdAt`** `object` - **`disk`** `number` - **`imageName`** `string` - **`memory`** `number` - **`state`** `string` - **`updatedAt`** `object` - **`description` (required)** `string | null` - **`error_message` (required)** `string | null` - **`host_id` (required)** `string | null` - **`id` (required)** `string` - **`provider` (required)** `string` - **`repository_id` (required)** `string | null` - **`repository_url` (required)** `string | null` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`snapshot` (required)** `string` - **`source_sandbox_id` (required)** `string | null` - **`source_sandbox_name` (required)** `string | null` - **`state` (required)** `string` - **`updated_at` (required)** `object` **Example:** ```json { "items": [ { "id": "", "snapshot": "", "provider": "", "host_id": null, "description": null, "source_sandbox_id": null, "source_sandbox_name": null, "repository_id": null, "repository_url": null, "base_snapshot": null, "sandbox_preset": null, "sandbox_size": null, "capture_mode": null, "state": "", "error_message": null, "created_at": "", "updated_at": "", "daytona": null } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Start capturing a snapshot from a running sandbox - **Method:** `POST` - **Path:** `/sandbox-snapshots` - **Tags:** SandboxSnapshots Validates the request, records a snapshot in the `capturing` state, and runs the (slow) Daytona capture in the background. Returns 202 immediately; poll the listing for the row to reach `active`/`failed`. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`description`** `string` - **`mode`** `string`, possible values: `"scrub_and_delete", "full"`, default: `"scrub_and_delete"` — scrub\_and\_delete (default): remove Amika-injected secrets (credential files + injected env vars) from the sandbox, capture the snapshot from the clean filesystem, then delete the source sandbox. full: capture everything as-is — including secrets — and keep the sandbox running. - **`sandbox_id`** `string` — Source sandbox, by id. - **`sandbox_name`** `string` — Source sandbox, by name. - **`sandbox_ref`** `string` — Source sandbox, by id or name; rejected if both match. **Example:** ```json { "sandbox_id": "", "sandbox_name": "", "sandbox_ref": "", "name": "", "description": "", "mode": "scrub_and_delete" } ``` #### Responses ##### Status: 202 Snapshot capture started. ###### Content-Type: application/json - **`base_snapshot` (required)** `string | null` - **`capture_mode` (required)** `string | null` - **`created_at` (required)** `object` - **`daytona` (required)** `object` - **`name` (required)** `string` - **`cpu`** `number` - **`createdAt`** `object` - **`disk`** `number` - **`imageName`** `string` - **`memory`** `number` - **`state`** `string` - **`updatedAt`** `object` - **`description` (required)** `string | null` - **`error_message` (required)** `string | null` - **`host_id` (required)** `string | null` - **`id` (required)** `string` - **`provider` (required)** `string` - **`repository_id` (required)** `string | null` - **`repository_url` (required)** `string | null` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`snapshot` (required)** `string` - **`source_sandbox_id` (required)** `string | null` - **`source_sandbox_name` (required)** `string | null` - **`state` (required)** `string` - **`updated_at` (required)** `object` **Example:** ```json { "id": "", "snapshot": "", "provider": "", "host_id": null, "description": null, "source_sandbox_id": null, "source_sandbox_name": null, "repository_id": null, "repository_url": null, "base_snapshot": null, "sandbox_preset": null, "sandbox_size": null, "capture_mode": null, "state": "", "error_message": null, "created_at": "", "updated_at": "", "daytona": { "name": "", "state": "", "imageName": "", "cpu": 1, "memory": 1, "disk": 1, "createdAt": "", "updatedAt": "" } } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Preview which injected secrets a 'snapshot and delete' would remove - **Method:** `GET` - **Path:** `/sandbox-snapshots/scrub-preview` - **Tags:** SandboxSnapshots #### Parameters ##### `sandbox` - **In:** `query` The sandbox whose injected secrets would be scrubbed. `string` — The sandbox whose injected secrets would be scrubbed. ##### `by` - **In:** `query` How to interpret `sandbox`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret \`sandbox\`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). ##### `sandbox_id` - **In:** `query` Deprecated: use `sandbox` with `by=id` instead. `string` — Deprecated: use \`sandbox\` with \`by=id\` instead. #### Responses ##### Status: 200 Secrets that would be scrubbed and files reset to a baseline (paths + names only). ###### Content-Type: application/json - **`env_vars` (required)** `array` **Items:** `string` - **`files` (required)** `array` **Items:** `string` - **`restored_files` (required)** `array` **Items:** `string` **Example:** ```json { "files": [ "" ], "restored_files": [ "" ], "env_vars": [ "" ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read a sandbox snapshot by name (default) or id - **Method:** `GET` - **Path:** `/sandbox-snapshots/{ref}` - **Tags:** SandboxSnapshots #### Parameters ##### `ref` required - **In:** `path` Snapshot reference: its fully-qualified name (default) or row id. Use the `by` query param to choose. `string` — Snapshot reference: its fully-qualified name (default) or row id. Use the \`by\` query param to choose. ##### `by` - **In:** `query` How to interpret the reference: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the reference: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). #### Responses ##### Status: 200 Snapshot. ###### Content-Type: application/json - **`base_snapshot` (required)** `string | null` - **`capture_mode` (required)** `string | null` - **`created_at` (required)** `object` - **`daytona` (required)** `object` - **`name` (required)** `string` - **`cpu`** `number` - **`createdAt`** `object` - **`disk`** `number` - **`imageName`** `string` - **`memory`** `number` - **`state`** `string` - **`updatedAt`** `object` - **`description` (required)** `string | null` - **`error_message` (required)** `string | null` - **`host_id` (required)** `string | null` - **`id` (required)** `string` - **`provider` (required)** `string` - **`repository_id` (required)** `string | null` - **`repository_url` (required)** `string | null` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`snapshot` (required)** `string` - **`source_sandbox_id` (required)** `string | null` - **`source_sandbox_name` (required)** `string | null` - **`state` (required)** `string` - **`updated_at` (required)** `object` **Example:** ```json { "id": "", "snapshot": "", "provider": "", "host_id": null, "description": null, "source_sandbox_id": null, "source_sandbox_name": null, "repository_id": null, "repository_url": null, "base_snapshot": null, "sandbox_preset": null, "sandbox_size": null, "capture_mode": null, "state": "", "error_message": null, "created_at": "", "updated_at": "", "daytona": { "name": "", "state": "", "imageName": "", "cpu": 1, "memory": 1, "disk": 1, "createdAt": "", "updatedAt": "" } } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a sandbox snapshot by name (default) or id - **Method:** `DELETE` - **Path:** `/sandbox-snapshots/{ref}` - **Tags:** SandboxSnapshots #### Parameters ##### `ref` required - **In:** `path` Snapshot reference: its fully-qualified name (default) or row id. Use the `by` query param to choose. `string` — Snapshot reference: its fully-qualified name (default) or row id. Use the \`by\` query param to choose. ##### `by` - **In:** `query` How to interpret the reference: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the reference: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). #### Responses ##### Status: 204 Deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List live sandbox services for the caller's org - **Method:** `GET` - **Path:** `/rig-services` - **Tags:** SandboxServices #### Parameters ##### `sandbox_id` - **In:** `query` Only this sandbox's services, by sandbox id. `string` — Only this sandbox's services, by sandbox id. ##### `sandbox_name` - **In:** `query` Only this sandbox's services, by sandbox name. `string` — Only this sandbox's services, by sandbox name. ##### `sandbox_ref` - **In:** `query` Only this sandbox's services, by id or name (rejected if both match). `string` — Only this sandbox's services, by id or name (rejected if both match). #### Responses ##### Status: 200 Services. ###### Content-Type: application/json - **`items` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`host_port` (required)** `integer | null` - **`id` (required)** `string | null` - **`kind` (required)** `string`, possible values: `"system", "user"` - **`name` (required)** `string` - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`sandbox_id` (required)** `string` - **`source` (required)** `string`, possible values: `"table", "legacy"` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` - **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "items": [ { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List sandbox-captured snapshots for the caller's org - **Method:** `GET` - **Path:** `/rig-snapshots` - **Tags:** SandboxSnapshots #### Parameters ##### `repository_id` - **In:** `query` If set, only return snapshots taken from sandboxes attached to this repository. `string` — If set, only return snapshots taken from sandboxes attached to this repository. ##### `source_sandbox_id` - **In:** `query` If set, only return snapshots captured from this sandbox. `string` — If set, only return snapshots captured from this sandbox. #### Responses ##### Status: 200 Snapshots. ###### Content-Type: application/json - **`items` (required)** `array` **Items:** - **`base_snapshot` (required)** `string | null` - **`capture_mode` (required)** `string | null` - **`created_at` (required)** `object` - **`daytona` (required)** `object` - **`name` (required)** `string` - **`cpu`** `number` - **`createdAt`** `object` - **`disk`** `number` - **`imageName`** `string` - **`memory`** `number` - **`state`** `string` - **`updatedAt`** `object` - **`description` (required)** `string | null` - **`error_message` (required)** `string | null` - **`host_id` (required)** `string | null` - **`id` (required)** `string` - **`provider` (required)** `string` - **`repository_id` (required)** `string | null` - **`repository_url` (required)** `string | null` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`snapshot` (required)** `string` - **`source_sandbox_id` (required)** `string | null` - **`source_sandbox_name` (required)** `string | null` - **`state` (required)** `string` - **`updated_at` (required)** `object` **Example:** ```json { "items": [ { "id": "", "snapshot": "", "provider": "", "host_id": null, "description": null, "source_sandbox_id": null, "source_sandbox_name": null, "repository_id": null, "repository_url": null, "base_snapshot": null, "sandbox_preset": null, "sandbox_size": null, "capture_mode": null, "state": "", "error_message": null, "created_at": "", "updated_at": "", "daytona": null } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Start capturing a snapshot from a running sandbox - **Method:** `POST` - **Path:** `/rig-snapshots` - **Tags:** SandboxSnapshots Validates the request, records a snapshot in the `capturing` state, and runs the (slow) Daytona capture in the background. Returns 202 immediately; poll the listing for the row to reach `active`/`failed`. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`description`** `string` - **`mode`** `string`, possible values: `"scrub_and_delete", "full"`, default: `"scrub_and_delete"` — scrub\_and\_delete (default): remove Amika-injected secrets (credential files + injected env vars) from the sandbox, capture the snapshot from the clean filesystem, then delete the source sandbox. full: capture everything as-is — including secrets — and keep the sandbox running. - **`sandbox_id`** `string` — Source sandbox, by id. - **`sandbox_name`** `string` — Source sandbox, by name. - **`sandbox_ref`** `string` — Source sandbox, by id or name; rejected if both match. **Example:** ```json { "sandbox_id": "", "sandbox_name": "", "sandbox_ref": "", "name": "", "description": "", "mode": "scrub_and_delete" } ``` #### Responses ##### Status: 202 Snapshot capture started. ###### Content-Type: application/json - **`base_snapshot` (required)** `string | null` - **`capture_mode` (required)** `string | null` - **`created_at` (required)** `object` - **`daytona` (required)** `object` - **`name` (required)** `string` - **`cpu`** `number` - **`createdAt`** `object` - **`disk`** `number` - **`imageName`** `string` - **`memory`** `number` - **`state`** `string` - **`updatedAt`** `object` - **`description` (required)** `string | null` - **`error_message` (required)** `string | null` - **`host_id` (required)** `string | null` - **`id` (required)** `string` - **`provider` (required)** `string` - **`repository_id` (required)** `string | null` - **`repository_url` (required)** `string | null` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`snapshot` (required)** `string` - **`source_sandbox_id` (required)** `string | null` - **`source_sandbox_name` (required)** `string | null` - **`state` (required)** `string` - **`updated_at` (required)** `object` **Example:** ```json { "id": "", "snapshot": "", "provider": "", "host_id": null, "description": null, "source_sandbox_id": null, "source_sandbox_name": null, "repository_id": null, "repository_url": null, "base_snapshot": null, "sandbox_preset": null, "sandbox_size": null, "capture_mode": null, "state": "", "error_message": null, "created_at": "", "updated_at": "", "daytona": { "name": "", "state": "", "imageName": "", "cpu": 1, "memory": 1, "disk": 1, "createdAt": "", "updatedAt": "" } } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Preview which injected secrets a 'snapshot and delete' would remove - **Method:** `GET` - **Path:** `/rig-snapshots/scrub-preview` - **Tags:** SandboxSnapshots #### Parameters ##### `sandbox` - **In:** `query` The sandbox whose injected secrets would be scrubbed. `string` — The sandbox whose injected secrets would be scrubbed. ##### `by` - **In:** `query` How to interpret `sandbox`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret \`sandbox\`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). ##### `sandbox_id` - **In:** `query` Deprecated: use `sandbox` with `by=id` instead. `string` — Deprecated: use \`sandbox\` with \`by=id\` instead. #### Responses ##### Status: 200 Secrets that would be scrubbed and files reset to a baseline (paths + names only). ###### Content-Type: application/json - **`env_vars` (required)** `array` **Items:** `string` - **`files` (required)** `array` **Items:** `string` - **`restored_files` (required)** `array` **Items:** `string` **Example:** ```json { "files": [ "" ], "restored_files": [ "" ], "env_vars": [ "" ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read a sandbox snapshot by name (default) or id - **Method:** `GET` - **Path:** `/rig-snapshots/{ref}` - **Tags:** SandboxSnapshots #### Parameters ##### `ref` required - **In:** `path` Snapshot reference: its fully-qualified name (default) or row id. Use the `by` query param to choose. `string` — Snapshot reference: its fully-qualified name (default) or row id. Use the \`by\` query param to choose. ##### `by` - **In:** `query` How to interpret the reference: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the reference: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). #### Responses ##### Status: 200 Snapshot. ###### Content-Type: application/json - **`base_snapshot` (required)** `string | null` - **`capture_mode` (required)** `string | null` - **`created_at` (required)** `object` - **`daytona` (required)** `object` - **`name` (required)** `string` - **`cpu`** `number` - **`createdAt`** `object` - **`disk`** `number` - **`imageName`** `string` - **`memory`** `number` - **`state`** `string` - **`updatedAt`** `object` - **`description` (required)** `string | null` - **`error_message` (required)** `string | null` - **`host_id` (required)** `string | null` - **`id` (required)** `string` - **`provider` (required)** `string` - **`repository_id` (required)** `string | null` - **`repository_url` (required)** `string | null` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`snapshot` (required)** `string` - **`source_sandbox_id` (required)** `string | null` - **`source_sandbox_name` (required)** `string | null` - **`state` (required)** `string` - **`updated_at` (required)** `object` **Example:** ```json { "id": "", "snapshot": "", "provider": "", "host_id": null, "description": null, "source_sandbox_id": null, "source_sandbox_name": null, "repository_id": null, "repository_url": null, "base_snapshot": null, "sandbox_preset": null, "sandbox_size": null, "capture_mode": null, "state": "", "error_message": null, "created_at": "", "updated_at": "", "daytona": { "name": "", "state": "", "imageName": "", "cpu": 1, "memory": 1, "disk": 1, "createdAt": "", "updatedAt": "" } } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a sandbox snapshot by name (default) or id - **Method:** `DELETE` - **Path:** `/rig-snapshots/{ref}` - **Tags:** SandboxSnapshots #### Parameters ##### `ref` required - **In:** `path` Snapshot reference: its fully-qualified name (default) or row id. Use the `by` query param to choose. `string` — Snapshot reference: its fully-qualified name (default) or row id. Use the \`by\` query param to choose. ##### `by` - **In:** `query` How to interpret the reference: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the reference: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). #### Responses ##### Status: 204 Deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Slack metadata for the org's Slack-made sandboxes - **Method:** `GET` - **Path:** `/sandboxes:slackMetadata` - **Tags:** Sandboxes #### Responses ##### Status: 200 Map of sandbox id to Slack metadata. ###### Content-Type: application/json - **`metadata` (required)** `object` **Example:** ```json { "metadata": { "additionalProperty": { "conversation_id": null, "team_id": "", "team_name": null, "team_icon_url": null, "channel_id": "", "channel_name": null, "thread_id": "", "preview": null, "status": null, "agent_name": "claude" } } } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Slack metadata for the org's Slack-made sandboxes - **Method:** `GET` - **Path:** `/rigs:slackMetadata` - **Tags:** Sandboxes #### Responses ##### Status: 200 Map of sandbox id to Slack metadata. ###### Content-Type: application/json - **`metadata` (required)** `object` **Example:** ```json { "metadata": { "additionalProperty": { "conversation_id": null, "team_id": "", "team_name": null, "team_icon_url": null, "channel_id": "", "channel_name": null, "thread_id": "", "preview": null, "status": null, "agent_name": "claude" } } } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Bind a sandbox to a GitHub branch or pull request - **Method:** `POST` - **Path:** `/sandboxes/{sandbox_ref}/bindings` - **Tags:** SandboxBindings #### Parameters ##### `sandbox_ref` required - **In:** `path` `string` ##### `sandbox_by` - **In:** `query` How to resolve the parent sandbox: ref/name\_or\_id (default), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to resolve the parent sandbox: ref/name\_or\_id (default), name, or id. #### Request Body ##### Content-Type: application/json **Any of:** - **`target_url` (required)** `string`, format: `uri` * **`target` (required)** `object` - **`branch` (required)** `string` - **`kind` (required)** `string`, possible values: `"github_branch"` - **`repository` (required)** `object` - **`name` (required)** `string` - **`owner` (required)** `string` * **`rebind`** `boolean`, default: `false` **Example:** ```json { "target_url": "" } ``` #### Responses ##### Status: 201 Binding created or already present. ###### Content-Type: application/json - **`id` (required)** `string` **Example:** ```json { "id": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List a sandbox's bindings - **Method:** `GET` - **Path:** `/sandboxes/{sandbox_ref}/bindings` - **Tags:** SandboxBindings #### Parameters ##### `sandbox_ref` required - **In:** `path` `string` ##### `sandbox_by` - **In:** `query` How to resolve the parent sandbox: ref/name\_or\_id (default), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to resolve the parent sandbox: ref/name\_or\_id (default), name, or id. #### Responses ##### Status: 200 Bindings. ###### Content-Type: application/json - **`items` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`created_by_id` (required)** `string` - **`created_by_kind` (required)** `string`, possible values: `"user", "system"` - **`id` (required)** `string` - **`metadata` (required)** `object` - **`relationship` (required)** `string` - **`sandbox_id` (required)** `string` - **`system_metadata` (required)** `object` - **`target_id` (required)** `string` - **`target_kind` (required)** `string` - **`target_namespace` (required)** `string` - **`target_url` (required)** `string`, format: `uri` - **`updated_at` (required)** `object` **Example:** ```json { "items": [ { "id": "", "sandbox_id": "", "target_namespace": "", "target_kind": "", "target_id": "", "target_url": "", "relationship": "", "metadata": {}, "system_metadata": {}, "created_by_kind": "user", "created_by_id": "", "created_at": "", "updated_at": "" } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List the org's sandboxes - **Method:** `GET` - **Path:** `/sandboxes` - **Tags:** Sandboxes #### Parameters ##### `host_id` - **In:** `query` If set, only return rigs on this one of the organization's own hosts. `string` — If set, only return rigs on this one of the organization's own hosts. #### Responses ##### Status: 200 Sandboxes. ###### Content-Type: application/json **Array of:** - **`amika_opencode_web` (required)** `string | null` - **`branch` (required)** `string | null` - **`commit_hash` (required)** `string | null` - **`created_at` (required)** `object` - **`current_session_id` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`provider` (required)** `string | null` - **`provider_sandbox_id` (required)** `string | null` - **`repo_id` (required)** `string | null` - **`repo_name` (required)** `string | null` - **`repo_provider` (required)** `string | null` - **`repo_url` (required)** `string | null` - **`services` (required)** `array` **Items:** - **`containerPort` (required)** `integer` - **`hostPort` (required)** `integer` - **`name` (required)** `string` - **`protocol` (required)** `string` - **`url` (required)** `string` - **`kind`** `string`, possible values: `"system", "user"` - **`snapshot` (required)** `string | null` - **`updated_at` (required)** `object` - **`user_id` (required)** `string | null` - **`agent_credentials`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`inject_target` (required)** `string | null` - **`kind` (required)** `string` - **`name` (required)** `string | null` - **`scope` (required)** `string | null`, possible values: `"user", "org", null` - **`agent_cwd`** `string | null` - **`created_by`** `object` - **`email` (required)** `string | null` - **`name` (required)** `string | null` - **`error_message`** `string | null` - **`github_auth_mode`** `string | null`, possible values: `"pat", "app_token", null` - **`github_credential_provisioned`** `boolean | null` - **`host_id`** `string | null` - **`mounted_secrets`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`managed` (required)** `boolean` - **`name` (required)** `string` - **`provider` (required)** `string | null` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`origin`** `string | null` - **`resolved_agent_credentials`** `array` **Items:** **One of:** - **`kind` (required)** `string` - **`name` (required)** `string` - **`outcome` (required)** `string`, possible values: `"resolved"` - **`source` (required)** `string` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` * **`kind` (required)** `string` * **`outcome` (required)** `string`, possible values: `"skipped"` * **`reason` (required)** `string`, possible values: `"request:none", "no_user_credential"` - **`sandbox_preset`** `string | null` - **`sandbox_size`** `string | null` - **`sandbox_size_config`** `object` - **`diskGib` (required)** `number` - **`diskGrowOnly` (required)** `boolean` - **`memoryGib` (required)** `number` - **`name` (required)** `string | null` - **`vcpus` (required)** `number` - **`secret_names`** `array` **Items:** `string` - **`setup_status`** `string | null`, possible values: `"ok", "setup-running", "git-failed", "setup-failed", "sys-setup-failed", null` - **`snapshot_name`** `string | null` - **`ssh_key_status`** `string`, possible values: `"ready", "no-key", "stale-keys", "unknown"` - **`state`** `string` - **`status`** `string`, possible values: `"creating", "starting", "running", "stopping", "stopped", "suspending", "suspended", "snapshotting", "failed", "unknown"` - **`urls_expire_at`** `object` **Example:** ```json [ { "id": "", "user_id": null, "org_id": "", "name": "", "provider": null, "provider_sandbox_id": null, "amika_opencode_web": null, "repo_name": null, "repo_provider": null, "repo_id": null, "repo_url": null, "branch": null, "commit_hash": null, "snapshot": null, "snapshot_name": null, "sandbox_preset": null, "sandbox_size": null, "sandbox_size_config": { "name": null, "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true }, "github_auth_mode": "pat", "github_credential_provisioned": null, "error_message": null, "current_session_id": null, "services": [ { "name": "", "url": "", "hostPort": 1, "containerPort": 1, "protocol": "", "kind": "system" } ], "state": "", "status": "creating", "setup_status": "ok", "urls_expire_at": "", "secret_names": [ "" ], "mounted_secrets": [ { "name": "", "scope": "user", "managed": true, "credential_type": "api_key", "provider": null } ], "resolved_agent_credentials": [ { "kind": "", "outcome": "resolved", "name": "", "type": "oauth", "source": "" } ], "agent_credentials": [ { "kind": "", "name": null, "scope": "user", "credential_type": "api_key", "inject_target": null } ], "created_by": { "name": null, "email": null }, "agent_cwd": null, "ssh_key_status": "ready", "origin": null, "host_id": null, "created_at": "", "updated_at": "" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a sandbox - **Method:** `POST` - **Path:** `/sandboxes` - **Tags:** Sandboxes #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`agent`** `string`, possible values: `"claude", "codex"` - **`agent_credentials`** `array`, default: `[]` **Items:** - **`kind` (required)** `string`, possible values: `"claude", "codex"` - **`name`** `string` - **`none`** `boolean`, possible values: `true` - **`type`** `string`, possible values: `"oauth", "api_key"` - **`amika_opencode_web`** `object` - **`auto_delete_interval`** `number` - **`auto_stop_interval`** `number` - **`branch`** `string` - **`disabled_repo_env_var_names`** `array`, default: `[]` **Items:** `string` - **`env_vars`** `object`, default: `{}` - **`git_url`** `string` - **`github_auth_mode`** `string`, possible values: `"pat", "app_token"` - **`github_url`** `string` - **`host_id`** `string` - **`initial_prompt`** `string` - **`integration_ids`** `array` **Items:** `string` - **`new_branch_name`** `string` - **`preset`** `string`, possible values: `"coder", "coder-plus-docker"` - **`provider`** `string`, possible values: `"daytona", "e2b", "freestyle", "vercel", "smol", "amika-hostd"` - **`repo_url`** `string` - **`resources`** `object` — With \`host\_id\`, the rig's resources, in place of a named \`size\`: 1 to 16 vCPUs, at least 64 MiB of memory in whole MiB, and a disk of at least 1 GiB. Requires \`host\_id\`, and cannot be combined with \`size\`. - **`diskGib` (required)** `integer` - **`memoryGib` (required)** `number` - **`vcpus` (required)** `integer` - **`secret_env_vars`** `object`, default: `{}` - **`setup_script_text`** `string` - **`size`** `string` — Providerless sandbox size (for example \`a0.m\`). Legacy names such as \`m\` and \`medium\` are also accepted. The provider is inferred from \`provider\` or the server default; when omitted, the size defaults to that provider's medium tier. With \`host\_id\`, names one of the host's own sizes instead; a host rig with neither \`size\` nor \`resources\` gets 4 vCPUs, 8 GiB of memory and a 20 GiB disk. - **`skip_setup_script`** `boolean`, default: `false` - **`snapshot`** `string | null` - **`workflow`** `object` - **`enabled` (required)** `boolean` **Example:** ```json { "name": "", "repo_url": "", "git_url": "", "github_url": "", "branch": "", "new_branch_name": "", "provider": "daytona", "host_id": "", "resources": { "vcpus": 1, "memoryGib": 0.0625, "diskGib": 1 }, "auto_stop_interval": 0, "auto_delete_interval": -1, "amika_opencode_web": "", "env_vars": {}, "secret_env_vars": {}, "disabled_repo_env_var_names": [], "setup_script_text": "", "skip_setup_script": false, "agent_credentials": [], "preset": "coder", "size": "", "snapshot": null, "integration_ids": [ "" ], "initial_prompt": "", "agent": "claude", "workflow": { "enabled": true }, "github_auth_mode": "pat" } ``` #### Responses ##### Status: 202 Sandbox created (provisioning continues in the background). ###### Content-Type: application/json - **`amika_opencode_web` (required)** `string | null` - **`branch` (required)** `string | null` - **`commit_hash` (required)** `string | null` - **`created_at` (required)** `object` - **`current_session_id` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`provider` (required)** `string | null` - **`provider_sandbox_id` (required)** `string | null` - **`repo_id` (required)** `string | null` - **`repo_name` (required)** `string | null` - **`repo_provider` (required)** `string | null` - **`repo_url` (required)** `string | null` - **`services` (required)** `array` **Items:** - **`containerPort` (required)** `integer` - **`hostPort` (required)** `integer` - **`name` (required)** `string` - **`protocol` (required)** `string` - **`url` (required)** `string` - **`kind`** `string`, possible values: `"system", "user"` - **`snapshot` (required)** `string | null` - **`updated_at` (required)** `object` - **`user_id` (required)** `string | null` - **`agent_credentials`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`inject_target` (required)** `string | null` - **`kind` (required)** `string` - **`name` (required)** `string | null` - **`scope` (required)** `string | null`, possible values: `"user", "org", null` - **`agent_cwd`** `string | null` - **`created_by`** `object` - **`email` (required)** `string | null` - **`name` (required)** `string | null` - **`error_message`** `string | null` - **`github_auth_mode`** `string | null`, possible values: `"pat", "app_token", null` - **`github_credential_provisioned`** `boolean | null` - **`host_id`** `string | null` - **`mounted_secrets`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`managed` (required)** `boolean` - **`name` (required)** `string` - **`provider` (required)** `string | null` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`origin`** `string | null` - **`resolved_agent_credentials`** `array` **Items:** **One of:** - **`kind` (required)** `string` - **`name` (required)** `string` - **`outcome` (required)** `string`, possible values: `"resolved"` - **`source` (required)** `string` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` * **`kind` (required)** `string` * **`outcome` (required)** `string`, possible values: `"skipped"` * **`reason` (required)** `string`, possible values: `"request:none", "no_user_credential"` - **`sandbox_preset`** `string | null` - **`sandbox_size`** `string | null` - **`sandbox_size_config`** `object` - **`diskGib` (required)** `number` - **`diskGrowOnly` (required)** `boolean` - **`memoryGib` (required)** `number` - **`name` (required)** `string | null` - **`vcpus` (required)** `number` - **`secret_names`** `array` **Items:** `string` - **`setup_status`** `string | null`, possible values: `"ok", "setup-running", "git-failed", "setup-failed", "sys-setup-failed", null` - **`snapshot_name`** `string | null` - **`ssh_key_status`** `string`, possible values: `"ready", "no-key", "stale-keys", "unknown"` - **`state`** `string` - **`status`** `string`, possible values: `"creating", "starting", "running", "stopping", "stopped", "suspending", "suspended", "snapshotting", "failed", "unknown"` - **`urls_expire_at`** `object` **Example:** ```json { "id": "", "user_id": null, "org_id": "", "name": "", "provider": null, "provider_sandbox_id": null, "amika_opencode_web": null, "repo_name": null, "repo_provider": null, "repo_id": null, "repo_url": null, "branch": null, "commit_hash": null, "snapshot": null, "snapshot_name": null, "sandbox_preset": null, "sandbox_size": null, "sandbox_size_config": { "name": null, "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true }, "github_auth_mode": "pat", "github_credential_provisioned": null, "error_message": null, "current_session_id": null, "services": [ { "name": "", "url": "", "hostPort": 1, "containerPort": 1, "protocol": "", "kind": "system" } ], "state": "", "status": "creating", "setup_status": "ok", "urls_expire_at": "", "secret_names": [ "" ], "mounted_secrets": [ { "name": "", "scope": "user", "managed": true, "credential_type": "api_key", "provider": null } ], "resolved_agent_credentials": [ { "kind": "", "outcome": "resolved", "name": "", "type": "oauth", "source": "" } ], "agent_credentials": [ { "kind": "", "name": null, "scope": "user", "credential_type": "api_key", "inject_target": null } ], "created_by": { "name": null, "email": null }, "agent_cwd": null, "ssh_key_status": "ready", "origin": null, "host_id": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read a sandbox by id or name - **Method:** `GET` - **Path:** `/sandboxes/{id}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Sandbox with its guest DNS hostname. ###### Content-Type: application/json **All of:** - **`amika_opencode_web` (required)** `string | null` - **`branch` (required)** `string | null` - **`commit_hash` (required)** `string | null` - **`created_at` (required)** `object` - **`current_session_id` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`provider` (required)** `string | null` - **`provider_sandbox_id` (required)** `string | null` - **`repo_id` (required)** `string | null` - **`repo_name` (required)** `string | null` - **`repo_provider` (required)** `string | null` - **`repo_url` (required)** `string | null` - **`services` (required)** `array` **Items:** - **`containerPort` (required)** `integer` - **`hostPort` (required)** `integer` - **`name` (required)** `string` - **`protocol` (required)** `string` - **`url` (required)** `string` - **`kind`** `string`, possible values: `"system", "user"` - **`snapshot` (required)** `string | null` - **`updated_at` (required)** `object` - **`user_id` (required)** `string | null` - **`agent_credentials`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`inject_target` (required)** `string | null` - **`kind` (required)** `string` - **`name` (required)** `string | null` - **`scope` (required)** `string | null`, possible values: `"user", "org", null` - **`agent_cwd`** `string | null` - **`created_by`** `object` - **`email` (required)** `string | null` - **`name` (required)** `string | null` - **`error_message`** `string | null` - **`github_auth_mode`** `string | null`, possible values: `"pat", "app_token", null` - **`github_credential_provisioned`** `boolean | null` - **`host_id`** `string | null` - **`mounted_secrets`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`managed` (required)** `boolean` - **`name` (required)** `string` - **`provider` (required)** `string | null` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`origin`** `string | null` - **`resolved_agent_credentials`** `array` **Items:** **One of:** - **`kind` (required)** `string` - **`name` (required)** `string` - **`outcome` (required)** `string`, possible values: `"resolved"` - **`source` (required)** `string` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` * **`kind` (required)** `string` * **`outcome` (required)** `string`, possible values: `"skipped"` * **`reason` (required)** `string`, possible values: `"request:none", "no_user_credential"` - **`sandbox_preset`** `string | null` - **`sandbox_size`** `string | null` - **`sandbox_size_config`** `object` - **`diskGib` (required)** `number` - **`diskGrowOnly` (required)** `boolean` - **`memoryGib` (required)** `number` - **`name` (required)** `string | null` - **`vcpus` (required)** `number` - **`secret_names`** `array` **Items:** `string` - **`setup_status`** `string | null`, possible values: `"ok", "setup-running", "git-failed", "setup-failed", "sys-setup-failed", null` - **`snapshot_name`** `string | null` - **`ssh_key_status`** `string`, possible values: `"ready", "no-key", "stale-keys", "unknown"` - **`state`** `string` - **`status`** `string`, possible values: `"creating", "starting", "running", "stopping", "stopped", "suspending", "suspended", "snapshotting", "failed", "unknown"` - **`urls_expire_at`** `object` * **`hostname` (required)** `string` **Example:** ```json { "id": "", "user_id": null, "org_id": "", "name": "", "provider": null, "provider_sandbox_id": null, "amika_opencode_web": null, "repo_name": null, "repo_provider": null, "repo_id": null, "repo_url": null, "branch": null, "commit_hash": null, "snapshot": null, "snapshot_name": null, "sandbox_preset": null, "sandbox_size": null, "sandbox_size_config": { "name": null, "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true }, "github_auth_mode": "pat", "github_credential_provisioned": null, "error_message": null, "current_session_id": null, "services": [ { "name": "", "url": "", "hostPort": 1, "containerPort": 1, "protocol": "", "kind": "system" } ], "state": "", "status": "creating", "setup_status": "ok", "urls_expire_at": "", "secret_names": [ "" ], "mounted_secrets": [ { "name": "", "scope": "user", "managed": true, "credential_type": "api_key", "provider": null } ], "resolved_agent_credentials": [ { "kind": "", "outcome": "resolved", "name": "", "type": "oauth", "source": "" } ], "agent_credentials": [ { "kind": "", "name": null, "scope": "user", "credential_type": "api_key", "inject_target": null } ], "created_by": { "name": null, "email": null }, "agent_cwd": null, "ssh_key_status": "ready", "origin": null, "host_id": null, "created_at": "", "updated_at": "", "hostname": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a sandbox - **Method:** `DELETE` - **Path:** `/sandboxes/{id}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Deleted. ###### Content-Type: application/json - **`ok` (required)** `boolean`, possible values: `true` **Example:** ```json { "ok": true } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Start a sandbox - **Method:** `POST` - **Path:** `/sandboxes/{id}/start` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `skip_start_script` - **In:** `query` `string`, possible values: `"true", "false"` #### Responses ##### Status: 202 Sandbox start scheduled. ###### Content-Type: application/json - **`ok` (required)** `boolean`, possible values: `true` **Example:** ```json { "ok": true } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Stop a sandbox - **Method:** `POST` - **Path:** `/sandboxes/{id}/stop` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 202 Sandbox stop scheduled. ###### Content-Type: application/json - **`ok` (required)** `boolean`, possible values: `true` **Example:** ```json { "ok": true } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a direct WebSocket SSH session - **Method:** `POST` - **Path:** `/sandboxes/{id}/ssh-sessions` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 One no-relay SSH transport descriptor. ###### Content-Type: application/json - **`connect_credential` (required)** `string` - **`connect_url` (required)** `string`, format: `uri` - **`host_public_key` (required)** `string` - **`sandbox_id` (required)** `string` - **`session_id` (required)** `string` - **`ssh_user` (required)** `string`, possible values: `"amika"` - **`transport` (required)** `string`, possible values: `"direct_ws"` **Example:** ```json { "session_id": "", "transport": "direct_ws", "connect_url": "", "connect_credential": "", "sandbox_id": "", "ssh_user": "amika", "host_public_key": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 503 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Mint a single-use web terminal ticket - **Method:** `POST` - **Path:** `/sandboxes/{id}/terminal-tickets` - **Tags:** Sandboxes Returns a short-lived, single-use credential for one web terminal WebSocket upgrade. The upgrade cannot use the browser's session cookie, because browsers do not apply the same-origin policy to WebSockets. #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 One single-use terminal ticket. ###### Content-Type: application/json - **`org_id` (required)** `string` - **`ticket` (required)** `string` **Example:** ```json { "ticket": "", "org_id": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List a sandbox's integrations - **Method:** `GET` - **Path:** `/sandboxes/{id}/integrations` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Integrations. ###### Content-Type: application/json **Array of:** - **`mcp_server_type` (required)** `string` - **`mcp_server_url` (required)** `string` - **`name` (required)** `string` - **`sandbox_id` (required)** `string` **Example:** ```json [ { "sandbox_id": "", "name": "", "mcp_server_type": "", "mcp_server_url": "" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read the Slack conversation thread for a Slack-made sandbox - **Method:** `GET` - **Path:** `/sandboxes/{id}/slack-conversation` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Conversation thread, or \`{ conversation: null }\` when the sandbox was not made by Slack or has no conversation yet. ###### Content-Type: application/json - **`conversation` (required)** `object` - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`channel_id` (required)** `string` - **`channel_name` (required)** `string | null` - **`conversation_id` (required)** `string` - **`messages` (required)** `array` **Items:** - **`author` (required)** `string` - **`contents` (required)** `string` - **`direction` (required)** `string`, possible values: `"inbound", "outbound"` - **`id` (required)** `string` - **`is_error` (required)** `boolean` - **`occurred_at` (required)** `object` - **`status` (required)** `string | null` - **`team_id` (required)** `string` - **`team_name` (required)** `string | null` - **`thread_id` (required)** `string` **Example:** ```json { "conversation": { "conversation_id": "", "team_id": "", "team_name": null, "channel_id": "", "channel_name": null, "thread_id": "", "status": null, "agent_name": "claude", "messages": [ { "id": "", "author": "", "direction": "inbound", "contents": "", "occurred_at": "", "is_error": true } ] } } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List a sandbox's agent sessions - **Method:** `GET` - **Path:** `/sandboxes/{id}/sessions` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `status` - **In:** `query` `string` ##### `limit` - **In:** `query` `integer` ##### `offset` - **In:** `query` `[ "integer", "null" ]` ##### `agent_name` - **In:** `query` `string` ##### `exclude_source` - **In:** `query` `string` ##### `source` - **In:** `query` `string` #### Responses ##### Status: 200 Sessions. ###### Content-Type: application/json - **`sessions` (required)** `array` **Items:** - **`agent_name` (required)** `string` - **`created_at` (required)** `object` - **`ended_at` (required)** `object` - **`id` (required)** `string` - **`metadata` (required)** `object` - **`org_id` (required)** `string` - **`sandbox_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` - **`preview`** `string | null` - **`total` (required)** `integer` **Example:** ```json { "sessions": [ { "id": "", "sandbox_id": "", "org_id": "", "agent_name": "", "status": "", "started_at": "", "ended_at": "", "metadata": {}, "preview": null, "created_at": "", "updated_at": "" } ], "total": 0 } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a new agent session - **Method:** `POST` - **Path:** `/sandboxes/{id}/sessions` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`agent_name` (required)** `string` - **`metadata`** `object` **Example:** ```json { "agent_name": "", "metadata": {} } ``` #### Responses ##### Status: 201 Session. ###### Content-Type: application/json **All of:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`messages` (required)** `array` **Items:** - **`content` (required)** `string` - **`role` (required)** `string` - **`timestamp` (required)** `string` - **`is_error`** `boolean` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "", "messages": [ { "role": "", "content": "", "timestamp": "", "is_error": true } ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read the latest agent session for a sandbox - **Method:** `GET` - **Path:** `/sandboxes/{id}/sessions/latest` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Session. ###### Content-Type: application/json **All of:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`messages` (required)** `array` **Items:** - **`content` (required)** `string` - **`role` (required)** `string` - **`timestamp` (required)** `string` - **`is_error`** `boolean` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "", "messages": [ { "role": "", "content": "", "timestamp": "", "is_error": true } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read an agent session - **Method:** `GET` - **Path:** `/sandboxes/{id}/sessions/{sessionId}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `sessionId` required - **In:** `path` `string` #### Responses ##### Status: 200 Session. ###### Content-Type: application/json **All of:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`messages` (required)** `array` **Items:** - **`content` (required)** `string` - **`role` (required)** `string` - **`timestamp` (required)** `string` - **`is_error`** `boolean` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "", "messages": [ { "role": "", "content": "", "timestamp": "", "is_error": true } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Update an agent session - **Method:** `PATCH` - **Path:** `/sandboxes/{id}/sessions/{sessionId}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `sessionId` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`metadata`** `object` - **`status`** `string`, possible values: `"active", "completed", "failed"` **Example:** ```json { "status": "active", "metadata": {} } ``` #### Responses ##### Status: 200 Updated session. ###### Content-Type: application/json **All of:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`messages` (required)** `array` **Items:** - **`content` (required)** `string` - **`role` (required)** `string` - **`timestamp` (required)** `string` - **`is_error`** `boolean` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "", "messages": [ { "role": "", "content": "", "timestamp": "", "is_error": true } ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read workflow events from the sandbox event sink - **Method:** `GET` - **Path:** `/sandboxes/{id}/workflow/events` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `since` - **In:** `query` `string` #### Responses ##### Status: 200 Events list (empty when the file is missing). ###### Content-Type: application/json - **`capped` (required)** `boolean` - **`count` (required)** `integer` - **`events` (required)** `array` **Items:** - **`event_type` (required)** `string` - **`id` (required)** `string` - **`time` (required)** `string` - **`contents`** `object` - **`step`** `string` **Example:** ```json { "events": [ { "event_type": "", "id": "", "time": "", "step": "", "contents": null } ], "count": 1, "capped": true } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read the control-plane lifecycle event feed for a sandbox - **Method:** `GET` - **Path:** `/sandboxes/{id}/lifecycle-events` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Lifecycle events, oldest first (empty when none). ###### Content-Type: application/json - **`count` (required)** `integer` - **`events` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`detail` (required)** `string | null` - **`id` (required)** `string` - **`run_kind` (required)** `string` - **`status` (required)** `string` - **`step` (required)** `string` **Example:** ```json { "events": [ { "id": "", "run_kind": "", "step": "", "status": "", "detail": null, "created_at": "" } ], "count": 1 } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List a sandbox's live services - **Method:** `GET` - **Path:** `/sandboxes/{id}/services` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. #### Responses ##### Status: 200 Services. ###### Content-Type: application/json - **`items` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`host_port` (required)** `integer | null` - **`id` (required)** `string | null` - **`kind` (required)** `string`, possible values: `"system", "user"` - **`name` (required)** `string` - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`sandbox_id` (required)** `string` - **`source` (required)** `string`, possible values: `"table", "legacy"` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` - **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "items": [ { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a live service on a sandbox - **Method:** `POST` - **Path:** `/sandboxes/{id}/services` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — Service name: a single DNS label, unique per sandbox. - **`port` (required)** `integer` — Container port the service listens on. - **`url_scheme` (required)** `string`, possible values: `"http", "https"` — URL scheme the gateway serves the service over. **Example:** ```json { "name": "", "port": 1, "url_scheme": "http" } ``` #### Responses ##### Status: 201 Service created. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`host_port` (required)** `integer | null` - **`id` (required)** `string | null` - **`kind` (required)** `string`, possible values: `"system", "user"` - **`name` (required)** `string` - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`sandbox_id` (required)** `string` - **`source` (required)** `string`, possible values: `"table", "legacy"` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` - **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Replace a live service on a sandbox - **Method:** `PUT` - **Path:** `/sandboxes/{id}/services/{ref}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `ref` required - **In:** `path` Service reference: its name (default) or row id. Use `by` to choose. `string` — Service reference: its name (default) or row id. Use \`by\` to choose. ##### `by` - **In:** `query` How to interpret the service `{ref}`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the service \`{ref}\`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — Service name: a single DNS label, unique per sandbox. - **`port` (required)** `integer` — Container port the service listens on. - **`url_scheme` (required)** `string`, possible values: `"http", "https"` — URL scheme the gateway serves the service over. **Example:** ```json { "name": "", "port": 1, "url_scheme": "http" } ``` #### Responses ##### Status: 200 Service replaced. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`host_port` (required)** `integer | null` - **`id` (required)** `string | null` - **`kind` (required)** `string`, possible values: `"system", "user"` - **`name` (required)** `string` - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`sandbox_id` (required)** `string` - **`source` (required)** `string`, possible values: `"table", "legacy"` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` - **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a live service from a sandbox - **Method:** `DELETE` - **Path:** `/sandboxes/{id}/services/{ref}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `ref` required - **In:** `path` Service reference: its name (default) or row id. Use `by` to choose. `string` — Service reference: its name (default) or row id. Use \`by\` to choose. ##### `by` - **In:** `query` How to interpret the service `{ref}`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the service \`{ref}\`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. #### Responses ##### Status: 204 Deleted. ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Mint a token for a service of a rig on your own host - **Method:** `POST` - **Path:** `/sandboxes/{id}/services/{ref}/tokens` - **Tags:** Sandboxes For callers that are not browsers, such as `curl` or a script: send the token in the returned `header` as `Bearer ` to the returned `url`. Only for rigs on the organization's own hosts; never for `amikad`. #### Parameters ##### `id` required - **In:** `path` `string` ##### `ref` required - **In:** `path` Service reference: its name (default) or row id. Use `by` to choose. `string` — Service reference: its name (default) or row id. Use \`by\` to choose. ##### `by` - **In:** `query` How to interpret the service `{ref}`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the service \`{ref}\`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. ##### `ttl_seconds` - **In:** `query` How long the token lives, in seconds: 1 to 86400. Defaults to an hour. `integer` — How long the token lives, in seconds: 1 to 86400. Defaults to an hour. #### Responses ##### Status: 201 Token minted. ###### Content-Type: application/json - **`expires_at` (required)** `object` - **`header` (required)** `string` — The request header the token goes in, as \`Bearer \\`. - **`token` (required)** `string` - **`url` (required)** `string` — The service's address on the rig's host, ending in \`/\`. It carries no credential. **Example:** ```json { "url": "", "header": "X-Amika-Authorization", "token": "", "expires_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 503 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List the org's sandboxes - **Method:** `GET` - **Path:** `/rigs` - **Tags:** Sandboxes #### Parameters ##### `host_id` - **In:** `query` If set, only return rigs on this one of the organization's own hosts. `string` — If set, only return rigs on this one of the organization's own hosts. #### Responses ##### Status: 200 Sandboxes. ###### Content-Type: application/json **Array of:** - **`amika_opencode_web` (required)** `string | null` - **`branch` (required)** `string | null` - **`commit_hash` (required)** `string | null` - **`created_at` (required)** `object` - **`current_session_id` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`provider` (required)** `string | null` - **`provider_sandbox_id` (required)** `string | null` - **`repo_id` (required)** `string | null` - **`repo_name` (required)** `string | null` - **`repo_provider` (required)** `string | null` - **`repo_url` (required)** `string | null` - **`services` (required)** `array` **Items:** - **`containerPort` (required)** `integer` - **`hostPort` (required)** `integer` - **`name` (required)** `string` - **`protocol` (required)** `string` - **`url` (required)** `string` - **`kind`** `string`, possible values: `"system", "user"` - **`snapshot` (required)** `string | null` - **`updated_at` (required)** `object` - **`user_id` (required)** `string | null` - **`agent_credentials`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`inject_target` (required)** `string | null` - **`kind` (required)** `string` - **`name` (required)** `string | null` - **`scope` (required)** `string | null`, possible values: `"user", "org", null` - **`agent_cwd`** `string | null` - **`created_by`** `object` - **`email` (required)** `string | null` - **`name` (required)** `string | null` - **`error_message`** `string | null` - **`github_auth_mode`** `string | null`, possible values: `"pat", "app_token", null` - **`github_credential_provisioned`** `boolean | null` - **`host_id`** `string | null` - **`mounted_secrets`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`managed` (required)** `boolean` - **`name` (required)** `string` - **`provider` (required)** `string | null` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`origin`** `string | null` - **`resolved_agent_credentials`** `array` **Items:** **One of:** - **`kind` (required)** `string` - **`name` (required)** `string` - **`outcome` (required)** `string`, possible values: `"resolved"` - **`source` (required)** `string` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` * **`kind` (required)** `string` * **`outcome` (required)** `string`, possible values: `"skipped"` * **`reason` (required)** `string`, possible values: `"request:none", "no_user_credential"` - **`sandbox_preset`** `string | null` - **`sandbox_size`** `string | null` - **`sandbox_size_config`** `object` - **`diskGib` (required)** `number` - **`diskGrowOnly` (required)** `boolean` - **`memoryGib` (required)** `number` - **`name` (required)** `string | null` - **`vcpus` (required)** `number` - **`secret_names`** `array` **Items:** `string` - **`setup_status`** `string | null`, possible values: `"ok", "setup-running", "git-failed", "setup-failed", "sys-setup-failed", null` - **`snapshot_name`** `string | null` - **`ssh_key_status`** `string`, possible values: `"ready", "no-key", "stale-keys", "unknown"` - **`state`** `string` - **`status`** `string`, possible values: `"creating", "starting", "running", "stopping", "stopped", "suspending", "suspended", "snapshotting", "failed", "unknown"` - **`urls_expire_at`** `object` **Example:** ```json [ { "id": "", "user_id": null, "org_id": "", "name": "", "provider": null, "provider_sandbox_id": null, "amika_opencode_web": null, "repo_name": null, "repo_provider": null, "repo_id": null, "repo_url": null, "branch": null, "commit_hash": null, "snapshot": null, "snapshot_name": null, "sandbox_preset": null, "sandbox_size": null, "sandbox_size_config": { "name": null, "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true }, "github_auth_mode": "pat", "github_credential_provisioned": null, "error_message": null, "current_session_id": null, "services": [ { "name": "", "url": "", "hostPort": 1, "containerPort": 1, "protocol": "", "kind": "system" } ], "state": "", "status": "creating", "setup_status": "ok", "urls_expire_at": "", "secret_names": [ "" ], "mounted_secrets": [ { "name": "", "scope": "user", "managed": true, "credential_type": "api_key", "provider": null } ], "resolved_agent_credentials": [ { "kind": "", "outcome": "resolved", "name": "", "type": "oauth", "source": "" } ], "agent_credentials": [ { "kind": "", "name": null, "scope": "user", "credential_type": "api_key", "inject_target": null } ], "created_by": { "name": null, "email": null }, "agent_cwd": null, "ssh_key_status": "ready", "origin": null, "host_id": null, "created_at": "", "updated_at": "" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a sandbox - **Method:** `POST` - **Path:** `/rigs` - **Tags:** Sandboxes #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`agent`** `string`, possible values: `"claude", "codex"` - **`agent_credentials`** `array`, default: `[]` **Items:** - **`kind` (required)** `string`, possible values: `"claude", "codex"` - **`name`** `string` - **`none`** `boolean`, possible values: `true` - **`type`** `string`, possible values: `"oauth", "api_key"` - **`amika_opencode_web`** `object` - **`auto_delete_interval`** `number` - **`auto_stop_interval`** `number` - **`branch`** `string` - **`disabled_repo_env_var_names`** `array`, default: `[]` **Items:** `string` - **`env_vars`** `object`, default: `{}` - **`git_url`** `string` - **`github_auth_mode`** `string`, possible values: `"pat", "app_token"` - **`github_url`** `string` - **`host_id`** `string` - **`initial_prompt`** `string` - **`integration_ids`** `array` **Items:** `string` - **`new_branch_name`** `string` - **`preset`** `string`, possible values: `"coder", "coder-plus-docker"` - **`provider`** `string`, possible values: `"daytona", "e2b", "freestyle", "vercel", "smol", "amika-hostd"` - **`repo_url`** `string` - **`resources`** `object` — With \`host\_id\`, the rig's resources, in place of a named \`size\`: 1 to 16 vCPUs, at least 64 MiB of memory in whole MiB, and a disk of at least 1 GiB. Requires \`host\_id\`, and cannot be combined with \`size\`. - **`diskGib` (required)** `integer` - **`memoryGib` (required)** `number` - **`vcpus` (required)** `integer` - **`secret_env_vars`** `object`, default: `{}` - **`setup_script_text`** `string` - **`size`** `string` — Providerless sandbox size (for example \`a0.m\`). Legacy names such as \`m\` and \`medium\` are also accepted. The provider is inferred from \`provider\` or the server default; when omitted, the size defaults to that provider's medium tier. With \`host\_id\`, names one of the host's own sizes instead; a host rig with neither \`size\` nor \`resources\` gets 4 vCPUs, 8 GiB of memory and a 20 GiB disk. - **`skip_setup_script`** `boolean`, default: `false` - **`snapshot`** `string | null` - **`workflow`** `object` - **`enabled` (required)** `boolean` **Example:** ```json { "name": "", "repo_url": "", "git_url": "", "github_url": "", "branch": "", "new_branch_name": "", "provider": "daytona", "host_id": "", "resources": { "vcpus": 1, "memoryGib": 0.0625, "diskGib": 1 }, "auto_stop_interval": 0, "auto_delete_interval": -1, "amika_opencode_web": "", "env_vars": {}, "secret_env_vars": {}, "disabled_repo_env_var_names": [], "setup_script_text": "", "skip_setup_script": false, "agent_credentials": [], "preset": "coder", "size": "", "snapshot": null, "integration_ids": [ "" ], "initial_prompt": "", "agent": "claude", "workflow": { "enabled": true }, "github_auth_mode": "pat" } ``` #### Responses ##### Status: 202 Sandbox created (provisioning continues in the background). ###### Content-Type: application/json - **`amika_opencode_web` (required)** `string | null` - **`branch` (required)** `string | null` - **`commit_hash` (required)** `string | null` - **`created_at` (required)** `object` - **`current_session_id` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`provider` (required)** `string | null` - **`provider_sandbox_id` (required)** `string | null` - **`repo_id` (required)** `string | null` - **`repo_name` (required)** `string | null` - **`repo_provider` (required)** `string | null` - **`repo_url` (required)** `string | null` - **`services` (required)** `array` **Items:** - **`containerPort` (required)** `integer` - **`hostPort` (required)** `integer` - **`name` (required)** `string` - **`protocol` (required)** `string` - **`url` (required)** `string` - **`kind`** `string`, possible values: `"system", "user"` - **`snapshot` (required)** `string | null` - **`updated_at` (required)** `object` - **`user_id` (required)** `string | null` - **`agent_credentials`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`inject_target` (required)** `string | null` - **`kind` (required)** `string` - **`name` (required)** `string | null` - **`scope` (required)** `string | null`, possible values: `"user", "org", null` - **`agent_cwd`** `string | null` - **`created_by`** `object` - **`email` (required)** `string | null` - **`name` (required)** `string | null` - **`error_message`** `string | null` - **`github_auth_mode`** `string | null`, possible values: `"pat", "app_token", null` - **`github_credential_provisioned`** `boolean | null` - **`host_id`** `string | null` - **`mounted_secrets`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`managed` (required)** `boolean` - **`name` (required)** `string` - **`provider` (required)** `string | null` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`origin`** `string | null` - **`resolved_agent_credentials`** `array` **Items:** **One of:** - **`kind` (required)** `string` - **`name` (required)** `string` - **`outcome` (required)** `string`, possible values: `"resolved"` - **`source` (required)** `string` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` * **`kind` (required)** `string` * **`outcome` (required)** `string`, possible values: `"skipped"` * **`reason` (required)** `string`, possible values: `"request:none", "no_user_credential"` - **`sandbox_preset`** `string | null` - **`sandbox_size`** `string | null` - **`sandbox_size_config`** `object` - **`diskGib` (required)** `number` - **`diskGrowOnly` (required)** `boolean` - **`memoryGib` (required)** `number` - **`name` (required)** `string | null` - **`vcpus` (required)** `number` - **`secret_names`** `array` **Items:** `string` - **`setup_status`** `string | null`, possible values: `"ok", "setup-running", "git-failed", "setup-failed", "sys-setup-failed", null` - **`snapshot_name`** `string | null` - **`ssh_key_status`** `string`, possible values: `"ready", "no-key", "stale-keys", "unknown"` - **`state`** `string` - **`status`** `string`, possible values: `"creating", "starting", "running", "stopping", "stopped", "suspending", "suspended", "snapshotting", "failed", "unknown"` - **`urls_expire_at`** `object` **Example:** ```json { "id": "", "user_id": null, "org_id": "", "name": "", "provider": null, "provider_sandbox_id": null, "amika_opencode_web": null, "repo_name": null, "repo_provider": null, "repo_id": null, "repo_url": null, "branch": null, "commit_hash": null, "snapshot": null, "snapshot_name": null, "sandbox_preset": null, "sandbox_size": null, "sandbox_size_config": { "name": null, "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true }, "github_auth_mode": "pat", "github_credential_provisioned": null, "error_message": null, "current_session_id": null, "services": [ { "name": "", "url": "", "hostPort": 1, "containerPort": 1, "protocol": "", "kind": "system" } ], "state": "", "status": "creating", "setup_status": "ok", "urls_expire_at": "", "secret_names": [ "" ], "mounted_secrets": [ { "name": "", "scope": "user", "managed": true, "credential_type": "api_key", "provider": null } ], "resolved_agent_credentials": [ { "kind": "", "outcome": "resolved", "name": "", "type": "oauth", "source": "" } ], "agent_credentials": [ { "kind": "", "name": null, "scope": "user", "credential_type": "api_key", "inject_target": null } ], "created_by": { "name": null, "email": null }, "agent_cwd": null, "ssh_key_status": "ready", "origin": null, "host_id": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read a sandbox by id or name - **Method:** `GET` - **Path:** `/rigs/{id}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Sandbox with its guest DNS hostname. ###### Content-Type: application/json **All of:** - **`amika_opencode_web` (required)** `string | null` - **`branch` (required)** `string | null` - **`commit_hash` (required)** `string | null` - **`created_at` (required)** `object` - **`current_session_id` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`provider` (required)** `string | null` - **`provider_sandbox_id` (required)** `string | null` - **`repo_id` (required)** `string | null` - **`repo_name` (required)** `string | null` - **`repo_provider` (required)** `string | null` - **`repo_url` (required)** `string | null` - **`services` (required)** `array` **Items:** - **`containerPort` (required)** `integer` - **`hostPort` (required)** `integer` - **`name` (required)** `string` - **`protocol` (required)** `string` - **`url` (required)** `string` - **`kind`** `string`, possible values: `"system", "user"` - **`snapshot` (required)** `string | null` - **`updated_at` (required)** `object` - **`user_id` (required)** `string | null` - **`agent_credentials`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`inject_target` (required)** `string | null` - **`kind` (required)** `string` - **`name` (required)** `string | null` - **`scope` (required)** `string | null`, possible values: `"user", "org", null` - **`agent_cwd`** `string | null` - **`created_by`** `object` - **`email` (required)** `string | null` - **`name` (required)** `string | null` - **`error_message`** `string | null` - **`github_auth_mode`** `string | null`, possible values: `"pat", "app_token", null` - **`github_credential_provisioned`** `boolean | null` - **`host_id`** `string | null` - **`mounted_secrets`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`managed` (required)** `boolean` - **`name` (required)** `string` - **`provider` (required)** `string | null` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`origin`** `string | null` - **`resolved_agent_credentials`** `array` **Items:** **One of:** - **`kind` (required)** `string` - **`name` (required)** `string` - **`outcome` (required)** `string`, possible values: `"resolved"` - **`source` (required)** `string` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` * **`kind` (required)** `string` * **`outcome` (required)** `string`, possible values: `"skipped"` * **`reason` (required)** `string`, possible values: `"request:none", "no_user_credential"` - **`sandbox_preset`** `string | null` - **`sandbox_size`** `string | null` - **`sandbox_size_config`** `object` - **`diskGib` (required)** `number` - **`diskGrowOnly` (required)** `boolean` - **`memoryGib` (required)** `number` - **`name` (required)** `string | null` - **`vcpus` (required)** `number` - **`secret_names`** `array` **Items:** `string` - **`setup_status`** `string | null`, possible values: `"ok", "setup-running", "git-failed", "setup-failed", "sys-setup-failed", null` - **`snapshot_name`** `string | null` - **`ssh_key_status`** `string`, possible values: `"ready", "no-key", "stale-keys", "unknown"` - **`state`** `string` - **`status`** `string`, possible values: `"creating", "starting", "running", "stopping", "stopped", "suspending", "suspended", "snapshotting", "failed", "unknown"` - **`urls_expire_at`** `object` * **`hostname` (required)** `string` **Example:** ```json { "id": "", "user_id": null, "org_id": "", "name": "", "provider": null, "provider_sandbox_id": null, "amika_opencode_web": null, "repo_name": null, "repo_provider": null, "repo_id": null, "repo_url": null, "branch": null, "commit_hash": null, "snapshot": null, "snapshot_name": null, "sandbox_preset": null, "sandbox_size": null, "sandbox_size_config": { "name": null, "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true }, "github_auth_mode": "pat", "github_credential_provisioned": null, "error_message": null, "current_session_id": null, "services": [ { "name": "", "url": "", "hostPort": 1, "containerPort": 1, "protocol": "", "kind": "system" } ], "state": "", "status": "creating", "setup_status": "ok", "urls_expire_at": "", "secret_names": [ "" ], "mounted_secrets": [ { "name": "", "scope": "user", "managed": true, "credential_type": "api_key", "provider": null } ], "resolved_agent_credentials": [ { "kind": "", "outcome": "resolved", "name": "", "type": "oauth", "source": "" } ], "agent_credentials": [ { "kind": "", "name": null, "scope": "user", "credential_type": "api_key", "inject_target": null } ], "created_by": { "name": null, "email": null }, "agent_cwd": null, "ssh_key_status": "ready", "origin": null, "host_id": null, "created_at": "", "updated_at": "", "hostname": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a sandbox - **Method:** `DELETE` - **Path:** `/rigs/{id}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Deleted. ###### Content-Type: application/json - **`ok` (required)** `boolean`, possible values: `true` **Example:** ```json { "ok": true } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Start a sandbox - **Method:** `POST` - **Path:** `/rigs/{id}/start` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `skip_start_script` - **In:** `query` `string`, possible values: `"true", "false"` #### Responses ##### Status: 202 Sandbox start scheduled. ###### Content-Type: application/json - **`ok` (required)** `boolean`, possible values: `true` **Example:** ```json { "ok": true } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Stop a sandbox - **Method:** `POST` - **Path:** `/rigs/{id}/stop` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 202 Sandbox stop scheduled. ###### Content-Type: application/json - **`ok` (required)** `boolean`, possible values: `true` **Example:** ```json { "ok": true } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a direct WebSocket SSH session - **Method:** `POST` - **Path:** `/rigs/{id}/ssh-sessions` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 One no-relay SSH transport descriptor. ###### Content-Type: application/json - **`connect_credential` (required)** `string` - **`connect_url` (required)** `string`, format: `uri` - **`host_public_key` (required)** `string` - **`sandbox_id` (required)** `string` - **`session_id` (required)** `string` - **`ssh_user` (required)** `string`, possible values: `"amika"` - **`transport` (required)** `string`, possible values: `"direct_ws"` **Example:** ```json { "session_id": "", "transport": "direct_ws", "connect_url": "", "connect_credential": "", "sandbox_id": "", "ssh_user": "amika", "host_public_key": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 503 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Mint a single-use web terminal ticket - **Method:** `POST` - **Path:** `/rigs/{id}/terminal-tickets` - **Tags:** Sandboxes Returns a short-lived, single-use credential for one web terminal WebSocket upgrade. The upgrade cannot use the browser's session cookie, because browsers do not apply the same-origin policy to WebSockets. #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 One single-use terminal ticket. ###### Content-Type: application/json - **`org_id` (required)** `string` - **`ticket` (required)** `string` **Example:** ```json { "ticket": "", "org_id": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List a sandbox's integrations - **Method:** `GET` - **Path:** `/rigs/{id}/integrations` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Integrations. ###### Content-Type: application/json **Array of:** - **`mcp_server_type` (required)** `string` - **`mcp_server_url` (required)** `string` - **`name` (required)** `string` - **`sandbox_id` (required)** `string` **Example:** ```json [ { "sandbox_id": "", "name": "", "mcp_server_type": "", "mcp_server_url": "" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read the Slack conversation thread for a Slack-made sandbox - **Method:** `GET` - **Path:** `/rigs/{id}/slack-conversation` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Conversation thread, or \`{ conversation: null }\` when the sandbox was not made by Slack or has no conversation yet. ###### Content-Type: application/json - **`conversation` (required)** `object` - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`channel_id` (required)** `string` - **`channel_name` (required)** `string | null` - **`conversation_id` (required)** `string` - **`messages` (required)** `array` **Items:** - **`author` (required)** `string` - **`contents` (required)** `string` - **`direction` (required)** `string`, possible values: `"inbound", "outbound"` - **`id` (required)** `string` - **`is_error` (required)** `boolean` - **`occurred_at` (required)** `object` - **`status` (required)** `string | null` - **`team_id` (required)** `string` - **`team_name` (required)** `string | null` - **`thread_id` (required)** `string` **Example:** ```json { "conversation": { "conversation_id": "", "team_id": "", "team_name": null, "channel_id": "", "channel_name": null, "thread_id": "", "status": null, "agent_name": "claude", "messages": [ { "id": "", "author": "", "direction": "inbound", "contents": "", "occurred_at": "", "is_error": true } ] } } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List a sandbox's agent sessions - **Method:** `GET` - **Path:** `/rigs/{id}/sessions` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `status` - **In:** `query` `string` ##### `limit` - **In:** `query` `integer` ##### `offset` - **In:** `query` `[ "integer", "null" ]` ##### `agent_name` - **In:** `query` `string` ##### `exclude_source` - **In:** `query` `string` ##### `source` - **In:** `query` `string` #### Responses ##### Status: 200 Sessions. ###### Content-Type: application/json - **`sessions` (required)** `array` **Items:** - **`agent_name` (required)** `string` - **`created_at` (required)** `object` - **`ended_at` (required)** `object` - **`id` (required)** `string` - **`metadata` (required)** `object` - **`org_id` (required)** `string` - **`sandbox_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` - **`preview`** `string | null` - **`total` (required)** `integer` **Example:** ```json { "sessions": [ { "id": "", "sandbox_id": "", "org_id": "", "agent_name": "", "status": "", "started_at": "", "ended_at": "", "metadata": {}, "preview": null, "created_at": "", "updated_at": "" } ], "total": 0 } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a new agent session - **Method:** `POST` - **Path:** `/rigs/{id}/sessions` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`agent_name` (required)** `string` - **`metadata`** `object` **Example:** ```json { "agent_name": "", "metadata": {} } ``` #### Responses ##### Status: 201 Session. ###### Content-Type: application/json **All of:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`messages` (required)** `array` **Items:** - **`content` (required)** `string` - **`role` (required)** `string` - **`timestamp` (required)** `string` - **`is_error`** `boolean` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "", "messages": [ { "role": "", "content": "", "timestamp": "", "is_error": true } ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read the latest agent session for a sandbox - **Method:** `GET` - **Path:** `/rigs/{id}/sessions/latest` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Session. ###### Content-Type: application/json **All of:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`messages` (required)** `array` **Items:** - **`content` (required)** `string` - **`role` (required)** `string` - **`timestamp` (required)** `string` - **`is_error`** `boolean` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "", "messages": [ { "role": "", "content": "", "timestamp": "", "is_error": true } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read an agent session - **Method:** `GET` - **Path:** `/rigs/{id}/sessions/{sessionId}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `sessionId` required - **In:** `path` `string` #### Responses ##### Status: 200 Session. ###### Content-Type: application/json **All of:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`messages` (required)** `array` **Items:** - **`content` (required)** `string` - **`role` (required)** `string` - **`timestamp` (required)** `string` - **`is_error`** `boolean` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "", "messages": [ { "role": "", "content": "", "timestamp": "", "is_error": true } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Update an agent session - **Method:** `PATCH` - **Path:** `/rigs/{id}/sessions/{sessionId}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `sessionId` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`metadata`** `object` - **`status`** `string`, possible values: `"active", "completed", "failed"` **Example:** ```json { "status": "active", "metadata": {} } ``` #### Responses ##### Status: 200 Updated session. ###### Content-Type: application/json **All of:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`messages` (required)** `array` **Items:** - **`content` (required)** `string` - **`role` (required)** `string` - **`timestamp` (required)** `string` - **`is_error`** `boolean` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "", "messages": [ { "role": "", "content": "", "timestamp": "", "is_error": true } ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read workflow events from the sandbox event sink - **Method:** `GET` - **Path:** `/rigs/{id}/workflow/events` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `since` - **In:** `query` `string` #### Responses ##### Status: 200 Events list (empty when the file is missing). ###### Content-Type: application/json - **`capped` (required)** `boolean` - **`count` (required)** `integer` - **`events` (required)** `array` **Items:** - **`event_type` (required)** `string` - **`id` (required)** `string` - **`time` (required)** `string` - **`contents`** `object` - **`step`** `string` **Example:** ```json { "events": [ { "event_type": "", "id": "", "time": "", "step": "", "contents": null } ], "count": 1, "capped": true } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read the control-plane lifecycle event feed for a sandbox - **Method:** `GET` - **Path:** `/rigs/{id}/lifecycle-events` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Lifecycle events, oldest first (empty when none). ###### Content-Type: application/json - **`count` (required)** `integer` - **`events` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`detail` (required)** `string | null` - **`id` (required)** `string` - **`run_kind` (required)** `string` - **`status` (required)** `string` - **`step` (required)** `string` **Example:** ```json { "events": [ { "id": "", "run_kind": "", "step": "", "status": "", "detail": null, "created_at": "" } ], "count": 1 } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List a sandbox's live services - **Method:** `GET` - **Path:** `/rigs/{id}/services` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. #### Responses ##### Status: 200 Services. ###### Content-Type: application/json - **`items` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`host_port` (required)** `integer | null` - **`id` (required)** `string | null` - **`kind` (required)** `string`, possible values: `"system", "user"` - **`name` (required)** `string` - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`sandbox_id` (required)** `string` - **`source` (required)** `string`, possible values: `"table", "legacy"` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` - **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "items": [ { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ] } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a live service on a sandbox - **Method:** `POST` - **Path:** `/rigs/{id}/services` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — Service name: a single DNS label, unique per sandbox. - **`port` (required)** `integer` — Container port the service listens on. - **`url_scheme` (required)** `string`, possible values: `"http", "https"` — URL scheme the gateway serves the service over. **Example:** ```json { "name": "", "port": 1, "url_scheme": "http" } ``` #### Responses ##### Status: 201 Service created. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`host_port` (required)** `integer | null` - **`id` (required)** `string | null` - **`kind` (required)** `string`, possible values: `"system", "user"` - **`name` (required)** `string` - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`sandbox_id` (required)** `string` - **`source` (required)** `string`, possible values: `"table", "legacy"` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` - **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Replace a live service on a sandbox - **Method:** `PUT` - **Path:** `/rigs/{id}/services/{ref}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `ref` required - **In:** `path` Service reference: its name (default) or row id. Use `by` to choose. `string` — Service reference: its name (default) or row id. Use \`by\` to choose. ##### `by` - **In:** `query` How to interpret the service `{ref}`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the service \`{ref}\`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — Service name: a single DNS label, unique per sandbox. - **`port` (required)** `integer` — Container port the service listens on. - **`url_scheme` (required)** `string`, possible values: `"http", "https"` — URL scheme the gateway serves the service over. **Example:** ```json { "name": "", "port": 1, "url_scheme": "http" } ``` #### Responses ##### Status: 200 Service replaced. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`host_port` (required)** `integer | null` - **`id` (required)** `string | null` - **`kind` (required)** `string`, possible values: `"system", "user"` - **`name` (required)** `string` - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`sandbox_id` (required)** `string` - **`source` (required)** `string`, possible values: `"table", "legacy"` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` - **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a live service from a sandbox - **Method:** `DELETE` - **Path:** `/rigs/{id}/services/{ref}` - **Tags:** Sandboxes #### Parameters ##### `id` required - **In:** `path` `string` ##### `ref` required - **In:** `path` Service reference: its name (default) or row id. Use `by` to choose. `string` — Service reference: its name (default) or row id. Use \`by\` to choose. ##### `by` - **In:** `query` How to interpret the service `{ref}`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the service \`{ref}\`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. #### Responses ##### Status: 204 Deleted. ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Mint a token for a service of a rig on your own host - **Method:** `POST` - **Path:** `/rigs/{id}/services/{ref}/tokens` - **Tags:** Sandboxes For callers that are not browsers, such as `curl` or a script: send the token in the returned `header` as `Bearer ` to the returned `url`. Only for rigs on the organization's own hosts; never for `amikad`. #### Parameters ##### `id` required - **In:** `path` `string` ##### `ref` required - **In:** `path` Service reference: its name (default) or row id. Use `by` to choose. `string` — Service reference: its name (default) or row id. Use \`by\` to choose. ##### `by` - **In:** `query` How to interpret the service `{ref}`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the service \`{ref}\`: name (default), id, or ref/name\_or\_id (matches either; rejects ambiguity). ##### `sandbox_by` - **In:** `query` How to interpret the sandbox `{id}` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. `string`, possible values: `"name", "id", "ref", "name_or_id"` — How to interpret the sandbox \`{id}\` path param: ref/name\_or\_id (default; matches an id or a name and rejects an ambiguous match), name, or id. ##### `ttl_seconds` - **In:** `query` How long the token lives, in seconds: 1 to 86400. Defaults to an hour. `integer` — How long the token lives, in seconds: 1 to 86400. Defaults to an hour. #### Responses ##### Status: 201 Token minted. ###### Content-Type: application/json - **`expires_at` (required)** `object` - **`header` (required)** `string` — The request header the token goes in, as \`Bearer \\`. - **`token` (required)** `string` - **`url` (required)** `string` — The service's address on the rig's host, ending in \`/\`. It carries no credential. **Example:** ```json { "url": "", "header": "X-Amika-Authorization", "token": "", "expires_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 503 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create or replace one user-owned SSH public key - **Method:** `POST` - **Path:** `/secrets/ssh-public-keys` - **Tags:** Secrets #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`public_key` (required)** `string` **Example:** ```json { "name": "", "public_key": "" } ``` #### Responses ##### Status: 201 SSH public key metadata. ###### Content-Type: application/json - **`id` (required)** `string` - **`name` (required)** `string` - **`public_key` (required)** `string` - **`scope` (required)** `string`, possible values: `"user"` **Example:** ```json { "id": "", "name": "", "public_key": "", "scope": "user" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List the caller's SSH public keys - **Method:** `GET` - **Path:** `/secrets/ssh-public-keys` - **Tags:** Secrets #### Responses ##### Status: 200 SSH public keys. ###### Content-Type: application/json **Array of:** - **`id` (required)** `string` - **`name` (required)** `string` - **`public_key` (required)** `string` - **`scope` (required)** `string`, possible values: `"user"` **Example:** ```json [ { "id": "", "name": "", "public_key": "", "scope": "user" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete one of the caller's SSH public keys - **Method:** `DELETE` - **Path:** `/secrets/ssh-public-keys/{id}` - **Tags:** Secrets Removes the key from the caller's set. This does not revoke access on sandboxes that are already provisioned: permitted keys are resolved at provision time, so the removal takes effect the next time a sandbox is provisioned, and it does not terminate sessions that are already open. #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 SSH public key deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List secrets visible to the caller - **Method:** `GET` - **Path:** `/secrets` - **Tags:** Secrets #### Responses ##### Status: 200 Secrets visible to the caller (user-scope + org-scope). ###### Content-Type: application/json **Array of:** - **`created_at` (required)** `object` - **`description` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`updated_at` (required)** `object` - **`user_id` (required)** `string` **Example:** ```json [ { "id": "", "org_id": "", "user_id": "", "name": "", "description": null, "scope": "user", "created_at": "", "updated_at": "" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a generic secret - **Method:** `POST` - **Path:** `/secrets` - **Tags:** Secrets #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`value` (required)** `string` - **`description`** `string | null` - **`scope`** `string`, possible values: `"user", "org"` **Example:** ```json { "name": "", "value": "", "scope": "user", "description": null } ``` #### Responses ##### Status: 201 Created secret summary. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`description` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`updated_at` (required)** `object` - **`user_id` (required)** `string` **Example:** ```json { "id": "", "org_id": "", "user_id": "", "name": "", "description": null, "scope": "user", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Update a generic secret - **Method:** `PUT` - **Path:** `/secrets/{id}` - **Tags:** Secrets #### Parameters ##### `id` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`description`** `string | null` - **`name`** `string` - **`scope`** `string`, possible values: `"user", "org"` - **`value`** `string` **Example:** ```json { "name": "", "value": "", "scope": "user", "description": null } ``` #### Responses ##### Status: 200 Updated secret summary. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`description` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`updated_at` (required)** `object` - **`user_id` (required)** `string` **Example:** ```json { "id": "", "org_id": "", "user_id": "", "name": "", "description": null, "scope": "user", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a generic secret - **Method:** `DELETE` - **Path:** `/secrets/{id}` - **Tags:** Secrets #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 Deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List Claude credentials - **Method:** `GET` - **Path:** `/secrets/claude` - **Tags:** Secrets #### Responses ##### Status: 200 Claude credential summaries. ###### Content-Type: application/json **Array of:** - **`id` (required)** `string` - **`name` (required)** `string` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` **Example:** ```json [ { "id": "", "name": "", "type": "oauth", "scope": "user" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a Claude credential - **Method:** `POST` - **Path:** `/secrets/claude` - **Tags:** Secrets #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` - **`value` (required)** `string` - **`scope`** `string`, possible values: `"user", "org"` **Example:** ```json { "name": "", "value": "", "type": "oauth", "scope": "user" } ``` #### Responses ##### Status: 201 Created Claude credential. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`description` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`updated_at` (required)** `object` - **`user_id` (required)** `string` **Example:** ```json { "id": "", "org_id": "", "user_id": "", "name": "", "description": null, "scope": "user", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a Claude credential - **Method:** `DELETE` - **Path:** `/secrets/claude/{id}` - **Tags:** Secrets #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 Deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Reveal a Claude credential value - **Method:** `POST` - **Path:** `/secrets/claude/{id}/reveal` - **Tags:** Secrets #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Credential value. ###### Content-Type: application/json - **`value` (required)** `string` **Example:** ```json { "value": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List Codex credentials - **Method:** `GET` - **Path:** `/secrets/codex` - **Tags:** Secrets #### Responses ##### Status: 200 Codex credential summaries. ###### Content-Type: application/json **Array of:** - **`id` (required)** `string` - **`name` (required)** `string` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` **Example:** ```json [ { "id": "", "name": "", "type": "oauth", "scope": "user" } ] ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a Codex credential - **Method:** `POST` - **Path:** `/secrets/codex` - **Tags:** Secrets #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` - **`value` (required)** `string` - **`scope`** `string`, possible values: `"user", "org"` **Example:** ```json { "name": "", "value": "", "type": "oauth", "scope": "user" } ``` #### Responses ##### Status: 201 Created Codex credential. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`description` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string` - **`org_id` (required)** `string` - **`scope` (required)** `string`, possible values: `"user", "org"` - **`updated_at` (required)** `object` - **`user_id` (required)** `string` **Example:** ```json { "id": "", "org_id": "", "user_id": "", "name": "", "description": null, "scope": "user", "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a Codex credential - **Method:** `DELETE` - **Path:** `/secrets/codex/{id}` - **Tags:** Secrets #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 Deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Reveal a Codex credential value - **Method:** `POST` - **Path:** `/secrets/codex/{id}/reveal` - **Tags:** Secrets #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Credential value. ###### Content-Type: application/json - **`value` (required)** `string` **Example:** ```json { "value": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read Pi credential status - **Method:** `GET` - **Path:** `/secrets/pi` - **Tags:** Secrets #### Responses ##### Status: 200 Pi credential status. ###### Content-Type: application/json - **`configured` (required)** `boolean` - **`secretId`** `string | null` **Example:** ```json { "configured": true, "secretId": null } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Save the Pi credential - **Method:** `POST` - **Path:** `/secrets/pi` - **Tags:** Secrets Store the `~/.pi/agent/auth.json` contents to inject into every sandbox, replacing any credential already configured. Supply either a pasted blob (`authJson`) or one of the org's Claude/Codex API keys to convert into one (`source`); a converted credential is a snapshot, not a link, so rotating the key means converting again. #### Request Body ##### Content-Type: application/json - **`authJson`** `string` - **`source`** `object` - **`agent` (required)** `string`, possible values: `"claude", "codex"` - **`secretId` (required)** `string` **Example:** ```json { "authJson": "", "source": { "agent": "claude", "secretId": "" } } ``` #### Responses ##### Status: 201 Saved. ###### Content-Type: application/json - **`configured` (required)** `boolean` - **`secretId`** `string | null` **Example:** ```json { "configured": true, "secretId": null } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete the Pi credential - **Method:** `DELETE` - **Path:** `/secrets/pi` - **Tags:** Secrets #### Responses ##### Status: 204 Deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Reveal the Pi credential - **Method:** `POST` - **Path:** `/secrets/pi/reveal` - **Tags:** Secrets #### Responses ##### Status: 200 Credential. ###### Content-Type: application/json - **`value` (required)** `string` **Example:** ```json { "value": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Reveal a generic secret value - **Method:** `POST` - **Path:** `/secrets/{id}/reveal` - **Tags:** Secrets #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 200 Secret value. ###### Content-Type: application/json - **`value` (required)** `string` **Example:** ```json { "value": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a service definition for a repository - **Method:** `POST` - **Path:** `/services` - **Tags:** Services #### Request Body ##### Content-Type: application/json **All of:** - **`repo_url` (required)** `string` * **`name` (required)** `string` * **`ports` (required)** `array` **Items:** - **`port` (required)** `integer` - **`protocol`** `string`, possible values: `"tcp", "udp"`, default: `"tcp"` - **`url_scheme`** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "repo_url": "", "name": "", "ports": [ { "port": 1, "protocol": "tcp", "url_scheme": "http" } ] } ``` #### Responses ##### Status: 201 Created service definition. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`id` (required)** `string` - **`name` (required)** `string` - **`ports` (required)** `array` **Items:** - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`url_scheme` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "id": "", "name": "", "ports": [ { "port": 1, "protocol": "", "url_scheme": null } ], "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 409 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Update a service definition - **Method:** `PUT` - **Path:** `/services/{id}` - **Tags:** Services #### Parameters ##### `id` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` - **`ports` (required)** `array` **Items:** - **`port` (required)** `integer` - **`protocol`** `string`, possible values: `"tcp", "udp"`, default: `"tcp"` - **`url_scheme`** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "name": "", "ports": [ { "port": 1, "protocol": "tcp", "url_scheme": "http" } ] } ``` #### Responses ##### Status: 200 Updated service definition. ###### Content-Type: application/json - **`created_at` (required)** `object` - **`id` (required)** `string` - **`name` (required)** `string` - **`ports` (required)** `array` **Items:** - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`url_scheme` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "id": "", "name": "", "ports": [ { "port": 1, "protocol": "", "url_scheme": null } ], "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete a service definition - **Method:** `DELETE` - **Path:** `/services/{id}` - **Tags:** Services #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 Deleted. ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read the org's Slack settings - **Method:** `GET` - **Path:** `/slack/settings` - **Tags:** Slack #### Responses ##### Status: 200 Slack settings. ###### Content-Type: application/json - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`created_at` (required)** `object` - **`org_id` (required)** `string` - **`repository_id` (required)** `string | null` - **`system_prompt` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "org_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Upsert the org's Slack settings - **Method:** `PUT` - **Path:** `/slack/settings` - **Tags:** Slack #### Request Body ##### Content-Type: application/json - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`repository_id` (required)** `string | null` - **`system_prompt` (required)** `string | null` **Example:** ```json { "repository_id": null, "agent_name": "claude", "system_prompt": null } ``` #### Responses ##### Status: 200 Updated settings. ###### Content-Type: application/json - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`created_at` (required)** `object` - **`org_id` (required)** `string` - **`repository_id` (required)** `string | null` - **`system_prompt` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "org_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List per-channel Slack settings and recently seen channels - **Method:** `GET` - **Path:** `/slack/channel-settings` - **Tags:** Slack #### Responses ##### Status: 200 Channel settings and the list of channels the bot has been mentioned in. ###### Content-Type: application/json - **`seen_channels` (required)** `array` **Items:** - **`last_seen_at` (required)** `object` - **`slack_channel_id` (required)** `string` - **`slack_channel_name` (required)** `string | null` - **`slack_team_id` (required)** `string` - **`slack_team_name` (required)** `string | null` - **`settings` (required)** `array` **Items:** - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`created_at` (required)** `object` - **`org_id` (required)** `string` - **`repository_id` (required)** `string | null` - **`slack_channel_id` (required)** `string` - **`slack_team_id` (required)** `string` - **`system_prompt` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "settings": [ { "org_id": "", "slack_team_id": "", "slack_channel_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ], "seen_channels": [ { "slack_team_id": "", "slack_team_name": null, "slack_channel_id": "", "slack_channel_name": null, "last_seen_at": "" } ] } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Upsert per-channel Slack settings - **Method:** `PUT` - **Path:** `/slack/channel-settings` - **Tags:** Slack #### Request Body ##### Content-Type: application/json - **`slack_channel_id` (required)** `string` - **`slack_team_id` (required)** `string` - **`agent_name`** `string | null`, possible values: `"claude", "codex", null` - **`repository_id`** `string | null` - **`system_prompt`** `string | null` **Example:** ```json { "slack_team_id": "", "slack_channel_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null } ``` #### Responses ##### Status: 200 Updated channel settings. ###### Content-Type: application/json - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`created_at` (required)** `object` - **`org_id` (required)** `string` - **`repository_id` (required)** `string | null` - **`slack_channel_id` (required)** `string` - **`slack_team_id` (required)** `string` - **`system_prompt` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "org_id": "", "slack_team_id": "", "slack_channel_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Delete per-channel Slack settings - **Method:** `DELETE` - **Path:** `/slack/channel-settings` - **Tags:** Slack #### Request Body ##### Content-Type: application/json - **`slack_channel_id` (required)** `string` - **`slack_team_id` (required)** `string` **Example:** ```json { "slack_team_id": "", "slack_channel_id": "" } ``` #### Responses ##### Status: 204 Deleted (or no row existed). ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Read the org's Linear default repo + agent settings - **Method:** `GET` - **Path:** `/linear/settings` - **Tags:** Linear #### Responses ##### Status: 200 Linear settings. ###### Content-Type: application/json - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`created_at` (required)** `object` - **`org_id` (required)** `string` - **`repository_id` (required)** `string | null` - **`system_prompt` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "org_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Upsert the org's Linear default repo + agent settings - **Method:** `PUT` - **Path:** `/linear/settings` - **Tags:** Linear #### Request Body ##### Content-Type: application/json - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`repository_id` (required)** `string | null` - **`system_prompt` (required)** `string | null` **Example:** ```json { "repository_id": null, "agent_name": "claude", "system_prompt": null } ``` #### Responses ##### Status: 200 Updated settings. ###### Content-Type: application/json - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`created_at` (required)** `object` - **`org_id` (required)** `string` - **`repository_id` (required)** `string | null` - **`system_prompt` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "org_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a one-time signed upload URL for the org's storage bucket - **Method:** `POST` - **Path:** `/storage/uploads` - **Tags:** Uploads #### Request Body ##### Content-Type: application/json - **`filename` (required)** `string` - **`upsert`** `boolean`, default: `false` **Example:** ```json { "filename": "", "upsert": false } ``` #### Responses ##### Status: 201 Signed upload URL. PUT the file body to \`upload\_url\` using the returned \`token\`; valid for \`expires\_in\` seconds, single use. ###### Content-Type: application/json - **`bucket` (required)** `string` - **`expires_in` (required)** `integer` - **`path` (required)** `string` - **`token` (required)** `string` - **`upload_url` (required)** `string` **Example:** ```json { "bucket": "", "path": "", "upload_url": "", "token": "", "expires_in": 1 } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 500 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create one-time signed upload URLs for several objects in one call - **Method:** `POST` - **Path:** `/storage/uploads/batch` - **Tags:** Uploads #### Request Body ##### Content-Type: application/json - **`files` (required)** `array` **Items:** - **`filename` (required)** `string` - **`upsert`** `boolean`, default: `false` **Example:** ```json { "files": [ { "filename": "", "upsert": false } ] } ``` #### Responses ##### Status: 201 One signed upload URL per requested file, in \`objects\`. PUT each file body to its \`upload\_url\` using its \`token\`; all are valid for \`expires\_in\` seconds, single use. The whole request fails if any single file cannot be signed. ###### Content-Type: application/json - **`bucket` (required)** `string` - **`expires_in` (required)** `integer` - **`objects` (required)** `array` **Items:** - **`path` (required)** `string` - **`token` (required)** `string` - **`upload_url` (required)** `string` **Example:** ```json { "bucket": "", "objects": [ { "path": "", "upload_url": "", "token": "" } ], "expires_in": 1 } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 500 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### List the org's bucket as a batch of signed download URLs (one per object) - **Method:** `GET` - **Path:** `/storage/downloads` - **Tags:** Downloads #### Parameters ##### `prefix` - **In:** `query` `string` ##### `cursor` - **In:** `query` `string` ##### `limit` - **In:** `query` `integer` #### Responses ##### Status: 200 A page of objects, each with a signed \`download\_url\`. Object \`key\`s preserve the bucket's directory structure, so a client can recreate the tree by writing each object to its \`key\`. URLs are valid for \`expires\_in\` seconds; follow \`next\_cursor\` for the next page. ###### Content-Type: application/json - **`bucket` (required)** `string` - **`expires_in` (required)** `integer` - **`next_cursor` (required)** `string | null` - **`objects` (required)** `array` **Items:** - **`download_url` (required)** `string` - **`key` (required)** `string` - **`last_modified`** `string` - **`size`** `integer` - **`prefix` (required)** `string` **Example:** ```json { "bucket": "", "prefix": "", "objects": [ { "key": "", "size": 1, "last_modified": "", "download_url": "" } ], "expires_in": 1, "next_cursor": null } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 500 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ### Create a signed download URL for an object in the org's bucket - **Method:** `POST` - **Path:** `/storage/downloads` - **Tags:** Downloads #### Request Body ##### Content-Type: application/json - **`filename` (required)** `string` - **`download`** `boolean`, default: `false` **Example:** ```json { "filename": "", "download": false } ``` #### Responses ##### Status: 201 Signed download URL. GET \`download\_url\` directly to fetch the object; valid for \`expires\_in\` seconds. ###### Content-Type: application/json - **`bucket` (required)** `string` - **`download_url` (required)** `string` - **`expires_in` (required)** `integer` - **`path` (required)** `string` **Example:** ```json { "bucket": "", "path": "", "download_url": "", "expires_in": 1 } ``` ##### Status: 400 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 401 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 403 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 404 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 500 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ##### Status: 502 Error ###### Content-Type: application/json - **`error_code` (required)** `string` - **`message` (required)** `string` - **`type` (required)** `string`, possible values: `"error"` - **`details`** `array` **Items:** - **`trace_id`** `string` **Example:** ```json { "type": "error", "error_code": "", "message": "", "details": [], "trace_id": "" } ``` ## Schemas ### AgentSessionSendResponse - **Type:**`object` * **`agent` (required)** `string`, possible values: `"claude", "codex"` * **`created_sandbox` (required)** `boolean` * **`is_error` (required)** `boolean` — True when the turn failed. The failure is still a 200: \`response\` carries the agent CLI's own message (e.g. "Not logged in · Please run /login"). * **`is_new_session` (required)** `boolean` * **`response` (required)** `string` * **`sandbox_id` (required)** `string` * **`session_id` (required)** `string` * **`usage`** `object` - **`cache_creation_tokens`** `integer` - **`cache_read_tokens`** `integer` - **`cost_usd`** `number` - **`duration_ms`** `integer` - **`input_tokens`** `integer` - **`num_turns`** `integer` - **`output_tokens`** `integer` **Example:** ```json { "session_id": "", "sandbox_id": "", "agent": "claude", "response": "", "is_error": true, "is_new_session": true, "created_sandbox": true, "usage": { "cost_usd": 1, "input_tokens": 0, "output_tokens": 0, "cache_read_tokens": 0, "cache_creation_tokens": 0, "duration_ms": 0, "num_turns": 0 } } ``` ### AgentSessionUsage - **Type:**`object` * **`cache_creation_tokens`** `integer` * **`cache_read_tokens`** `integer` * **`cost_usd`** `number` * **`duration_ms`** `integer` * **`input_tokens`** `integer` * **`num_turns`** `integer` * **`output_tokens`** `integer` **Example:** ```json { "cost_usd": 1, "input_tokens": 0, "output_tokens": 0, "cache_read_tokens": 0, "cache_creation_tokens": 0, "duration_ms": 0, "num_turns": 0 } ``` ### AgentSessionSendRequest - **Type:**`object` * **`message` (required)** `string` * **`agent`** `string`, possible values: `"claude", "codex"` * **`branch`** `string` * **`effort`** `string | null`, possible values: `"low", "medium", "high", "xhigh", "max", null` * **`model`** `string | null`, possible values: `"fable", "opus", "sonnet", "haiku", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.2", null` * **`new_branch_name`** `string` * **`new_session`** `boolean` * **`repo_url`** `string` * **`sandbox_id`** `string` * **`session_id`** `string` **Example:** ```json { "message": "", "agent": "claude", "session_id": "", "sandbox_id": "", "new_session": true, "model": "fable", "effort": "low", "repo_url": "", "branch": "", "new_branch_name": "" } ``` ### AgentSessionStreamFrame - **Type:** **Example:** ### ListAgentSessionsResponse - **Type:**`object` * **`sessions` (required)** `array` **Items:** - **`agent` (required)** `string` - **`created_at` (required)** `object` - **`effort` (required)** `string | null` - **`ended_at` (required)** `object` - **`model` (required)** `string | null` - **`preview` (required)** `string | null` - **`sandbox_id` (required)** `string` - **`sandbox_name` (required)** `string | null` - **`session_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` * **`total` (required)** `integer` **Example:** ```json { "sessions": [ { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "" } ], "total": 0 } ``` ### AgentSessionSummary - **Type:**`object` * **`agent` (required)** `string` * **`created_at` (required)** `object` * **`effort` (required)** `string | null` * **`ended_at` (required)** `object` * **`model` (required)** `string | null` * **`preview` (required)** `string | null` * **`sandbox_id` (required)** `string` * **`sandbox_name` (required)** `string | null` * **`session_id` (required)** `string` * **`started_at` (required)** `object` * **`status` (required)** `string` * **`updated_at` (required)** `object` **Example:** ```json { "session_id": "", "sandbox_id": "", "sandbox_name": null, "agent": "", "status": "", "preview": null, "model": null, "effort": null, "started_at": "", "ended_at": "", "created_at": "", "updated_at": "" } ``` ### AgentSessionDetail - **Type:** **Example:** ### AgentSessionMessage - **Type:**`object` * **`content` (required)** `string` * **`role` (required)** `string` * **`timestamp` (required)** `string` * **`is_error`** `boolean` **Example:** ```json { "role": "", "content": "", "timestamp": "", "is_error": true } ``` ### AgentSessionEventFrame - **Type:**`object` * **`created_at` (required)** `object` * **`id` (required)** `string` * **`kind` (required)** `string` * **`payload` (required)** `object` * **`seq` (required)** `integer` **Example:** ```json { "seq": 0, "id": "", "kind": "", "payload": {}, "created_at": "" } ``` ### ListApiKeysResponse - **Type:**`object` * **`data` (required)** `array` **Items:** - **`createdAt` (required)** `string` - **`id` (required)** `string` - **`lastUsedAt` (required)** `string | null` - **`name` (required)** `string` - **`obfuscatedValue` (required)** `string` - **`scope` (required)** `string`, possible values: `"organization", "user"` — Whether the key is scoped to the caller's organization or to the individual user who owns it. - **`updatedAt` (required)** `string` * **`pageInfo` (required)** `object` - **`after` (required)** `string | null` - **`hasNextPage` (required)** `boolean` **Example:** ```json { "data": [ { "id": "", "name": "", "scope": "organization", "obfuscatedValue": "", "lastUsedAt": null, "createdAt": "", "updatedAt": "" } ], "pageInfo": { "after": null, "hasNextPage": true } } ``` ### ApiKeySummary - **Type:**`object` * **`createdAt` (required)** `string` * **`id` (required)** `string` * **`lastUsedAt` (required)** `string | null` * **`name` (required)** `string` * **`obfuscatedValue` (required)** `string` * **`scope` (required)** `string`, possible values: `"organization", "user"` — Whether the key is scoped to the caller's organization or to the individual user who owns it. * **`updatedAt` (required)** `string` **Example:** ```json { "id": "", "name": "", "scope": "organization", "obfuscatedValue": "", "lastUsedAt": null, "createdAt": "", "updatedAt": "" } ``` ### ApiKeyWithValue - **Type:** **Example:** ### CreateApiKeyRequest - **Type:**`object` * **`name` (required)** `string` — Human-readable name for the API key. * **`scope`** `string`, possible values: `"organization", "user"`, default: `"organization"` — Scope of the key to create. Defaults to \`organization\`; pass \`user\` to mint a key owned by the calling user. **Example:** ```json { "name": "", "scope": "organization" } ``` ### ListDockerRegistriesResponse - **Type:**`array` **Example:** ### DockerRegistry - **Type:**`object` * **`created_at` (required)** `object` * **`daytona_registry_id` (required)** `string` * **`id` (required)** `string` * **`name` (required)** `string` * **`org_id` (required)** `string` * **`updated_at` (required)** `object` * **`url` (required)** `string` * **`registry_type`** `string | null` * **`username`** `string | null` **Example:** ```json { "id": "", "org_id": "", "name": "", "url": "", "daytona_registry_id": "", "created_at": "", "updated_at": "", "username": null, "registry_type": null } ``` ### CreateDockerRegistryRequest - **Type:**`object` * **`name` (required)** `string` * **`password` (required)** `string` * **`url` (required)** `string` * **`username` (required)** `string` * **`project`** `string` **Example:** ```json { "name": "", "url": "", "username": "", "password": "", "project": "" } ``` ### GitUserSettingsResponse - **Type:** **Example:** ### GitUserSettingsRow - **Type:**`object` * **`created_at` (required)** `string` * **`email` (required)** `string` * **`id` (required)** `string` * **`name` (required)** `string` * **`org_id` (required)** `string` * **`updated_at` (required)** `string` * **`user_id` (required)** `string` **Example:** ```json { "id": "", "org_id": "", "user_id": "", "name": "", "email": "", "created_at": "", "updated_at": "" } ``` ### UpsertGitUserSettingsRequest - **Type:**`object` * **`email` (required)** `string` * **`name` (required)** `string` **Example:** ```json { "name": "", "email": "" } ``` ### Host - **Type:**`object` * **`created_at` (required)** `object` * **`hostname` (required)** `string` * **`id` (required)** `string` * **`org_id` (required)** `string` * **`sizes` (required)** `object` * **`updated_at` (required)** `object` * **`url` (required)** `string | null` **Example:** ```json { "id": "", "hostname": "", "url": null, "org_id": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } }, "created_at": "", "updated_at": "" } ``` ### CreateHostRequest - **Type:**`object` * **`hostname` (required)** `string` * **`secret` (required)** `string` * **`sizes`** `object` * **`url`** `string | null`, format: `uri` **Example:** ```json { "hostname": "", "url": null, "secret": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } } } ``` ### ReplaceHostRequest - **Type:**`object` * **`hostname` (required)** `string` * **`secret`** `string` * **`sizes`** `object` * **`url`** `string | null`, format: `uri` **Example:** ```json { "hostname": "", "url": null, "secret": "", "sizes": { "additionalProperty": { "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true } } } ``` ### RevealHostSecretResponse - **Type:**`object` * **`value` (required)** `string` **Example:** ```json { "value": "" } ``` ### ListIntegrationCredentialsResponse - **Type:**`array` **Example:** ### ListRepositoriesResponse - **Type:**`array` **Example:** ### Repository - **Type:**`object` * **`created_at` (required)** `object` * **`default_snapshot` (required)** `string | null` * **`id` (required)** `string` * **`org_id` (required)** `string` * **`repo_url` (required)** `string` * **`sandbox_preset` (required)** `string | null` * **`sandbox_size` (required)** `string | null` * **`setup_script` (required)** `string | null` * **`start_script` (required)** `string | null` * **`updated_at` (required)** `object` * **`user_id` (required)** `string | null` **Example:** ```json { "id": "", "org_id": "", "user_id": null, "repo_url": "", "setup_script": null, "start_script": null, "sandbox_preset": null, "sandbox_size": null, "default_snapshot": null, "created_at": "", "updated_at": "" } ``` ### CreateRepositoryRequest - **Type:**`object` * **`repo_url` (required)** `string` * **`default_snapshot`** `string | null` * **`sandbox_preset`** `string | null` * **`sandbox_size`** `string | null` * **`setup_script`** `string` * **`start_script`** `string` **Example:** ```json { "repo_url": "", "setup_script": "", "start_script": "", "sandbox_preset": null, "sandbox_size": null, "default_snapshot": null } ``` ### RepoIntegrationsResponse - **Type:**`array` **Example:** ### UpsertIntegrationsRequest - **Type:**`object` * **`integrations` (required)** `array` **Items:** **One of:** - **`mcp_server_type` (required)** `string`, possible values: `"http"` - **`mcp_server_url` (required)** `string`, format: `uri` - **`name` (required)** `string` * **`mcp_server_type` (required)** `string`, possible values: `"stdio"` * **`name` (required)** `string`, possible values: `"playwright"` * **`mcp_server_url`** `string`, default: `""` **Example:** ```json { "integrations": [ { "name": "", "mcp_server_type": "http", "mcp_server_url": "" } ] } ``` ### WorkflowResponse - **Type:**`object` * **`workflow` (required)** `object` - **`created_at` (required)** `object` - **`default_agent` (required)** `string | null` - **`start_step` (required)** `string` - **`steps` (required)** `array` **Items:** - **`body` (required)** `string` - **`name` (required)** `string` - **`on_failure` (required)** `string | null` - **`on_success` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "workflow": { "default_agent": null, "start_step": "", "steps": [ { "name": "", "body": "", "on_success": null, "on_failure": null } ], "created_at": "", "updated_at": "" } } ``` ### UpsertWorkflowRequest - **Type:**`object` * **`start_step` (required)** `string` * **`steps` (required)** `array` **Items:** - **`body` (required)** `string` - **`name` (required)** `string` - **`on_failure`** `string | null` - **`on_success`** `string | null` * **`default_agent`** `string | null`, possible values: `"claude", "codex", null` **Example:** ```json { "default_agent": "claude", "start_step": "", "steps": [ { "name": "", "body": "", "on_success": null, "on_failure": null } ] } ``` ### ListSandboxBindingsResponse - **Type:**`object` * **`items` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`created_by_id` (required)** `string` - **`created_by_kind` (required)** `string`, possible values: `"user", "system"` - **`id` (required)** `string` - **`metadata` (required)** `object` - **`relationship` (required)** `string` - **`sandbox_id` (required)** `string` - **`system_metadata` (required)** `object` - **`target_id` (required)** `string` - **`target_kind` (required)** `string` - **`target_namespace` (required)** `string` - **`target_url` (required)** `string`, format: `uri` - **`updated_at` (required)** `object` **Example:** ```json { "items": [ { "id": "", "sandbox_id": "", "target_namespace": "", "target_kind": "", "target_id": "", "target_url": "", "relationship": "", "metadata": {}, "system_metadata": {}, "created_by_kind": "user", "created_by_id": "", "created_at": "", "updated_at": "" } ] } ``` ### SandboxBinding - **Type:**`object` * **`created_at` (required)** `object` * **`created_by_id` (required)** `string` * **`created_by_kind` (required)** `string`, possible values: `"user", "system"` * **`id` (required)** `string` * **`metadata` (required)** `object` * **`relationship` (required)** `string` * **`sandbox_id` (required)** `string` * **`system_metadata` (required)** `object` * **`target_id` (required)** `string` * **`target_kind` (required)** `string` * **`target_namespace` (required)** `string` * **`target_url` (required)** `string`, format: `uri` * **`updated_at` (required)** `object` **Example:** ```json { "id": "", "sandbox_id": "", "target_namespace": "", "target_kind": "", "target_id": "", "target_url": "", "relationship": "", "metadata": {}, "system_metadata": {}, "created_by_kind": "user", "created_by_id": "", "created_at": "", "updated_at": "" } ``` ### ListSandboxServicesResponse - **Type:**`object` * **`items` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`host_port` (required)** `integer | null` - **`id` (required)** `string | null` - **`kind` (required)** `string`, possible values: `"system", "user"` - **`name` (required)** `string` - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`sandbox_id` (required)** `string` - **`source` (required)** `string`, possible values: `"table", "legacy"` - **`updated_at` (required)** `object` - **`url` (required)** `string | null` - **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "items": [ { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ] } ``` ### SandboxService - **Type:**`object` * **`created_at` (required)** `object` * **`host_port` (required)** `integer | null` * **`id` (required)** `string | null` * **`kind` (required)** `string`, possible values: `"system", "user"` * **`name` (required)** `string` * **`port` (required)** `integer` * **`protocol` (required)** `string` * **`sandbox_id` (required)** `string` * **`source` (required)** `string`, possible values: `"table", "legacy"` * **`updated_at` (required)** `object` * **`url` (required)** `string | null` * **`url_scheme` (required)** `string | null`, possible values: `"http", "https", null` **Example:** ```json { "id": null, "sandbox_id": "", "name": "", "port": 1, "url_scheme": "http", "protocol": "", "url": null, "host_port": null, "source": "table", "kind": "system", "created_at": "", "updated_at": "" } ``` ### ListSandboxSnapshotsResponse - **Type:**`object` * **`items` (required)** `array` **Items:** - **`base_snapshot` (required)** `string | null` - **`capture_mode` (required)** `string | null` - **`created_at` (required)** `object` - **`daytona` (required)** `object` - **`name` (required)** `string` - **`cpu`** `number` - **`createdAt`** `object` - **`disk`** `number` - **`imageName`** `string` - **`memory`** `number` - **`state`** `string` - **`updatedAt`** `object` - **`description` (required)** `string | null` - **`error_message` (required)** `string | null` - **`host_id` (required)** `string | null` - **`id` (required)** `string` - **`provider` (required)** `string` - **`repository_id` (required)** `string | null` - **`repository_url` (required)** `string | null` - **`sandbox_preset` (required)** `string | null` - **`sandbox_size` (required)** `string | null` - **`snapshot` (required)** `string` - **`source_sandbox_id` (required)** `string | null` - **`source_sandbox_name` (required)** `string | null` - **`state` (required)** `string` - **`updated_at` (required)** `object` **Example:** ```json { "items": [ { "id": "", "snapshot": "", "provider": "", "host_id": null, "description": null, "source_sandbox_id": null, "source_sandbox_name": null, "repository_id": null, "repository_url": null, "base_snapshot": null, "sandbox_preset": null, "sandbox_size": null, "capture_mode": null, "state": "", "error_message": null, "created_at": "", "updated_at": "", "daytona": null } ] } ``` ### SandboxSnapshot - **Type:**`object` * **`base_snapshot` (required)** `string | null` * **`capture_mode` (required)** `string | null` * **`created_at` (required)** `object` * **`daytona` (required)** `object` - **`name` (required)** `string` - **`cpu`** `number` - **`createdAt`** `object` - **`disk`** `number` - **`imageName`** `string` - **`memory`** `number` - **`state`** `string` - **`updatedAt`** `object` * **`description` (required)** `string | null` * **`error_message` (required)** `string | null` * **`host_id` (required)** `string | null` * **`id` (required)** `string` * **`provider` (required)** `string` * **`repository_id` (required)** `string | null` * **`repository_url` (required)** `string | null` * **`sandbox_preset` (required)** `string | null` * **`sandbox_size` (required)** `string | null` * **`snapshot` (required)** `string` * **`source_sandbox_id` (required)** `string | null` * **`source_sandbox_name` (required)** `string | null` * **`state` (required)** `string` * **`updated_at` (required)** `object` **Example:** ```json { "id": "", "snapshot": "", "provider": "", "host_id": null, "description": null, "source_sandbox_id": null, "source_sandbox_name": null, "repository_id": null, "repository_url": null, "base_snapshot": null, "sandbox_preset": null, "sandbox_size": null, "capture_mode": null, "state": "", "error_message": null, "created_at": "", "updated_at": "", "daytona": { "name": "", "state": "", "imageName": "", "cpu": 1, "memory": 1, "disk": 1, "createdAt": "", "updatedAt": "" } } ``` ### ExperimentalDaytonaSnapshot - **Type:**`object` * **`name` (required)** `string` * **`cpu`** `number` * **`createdAt`** `object` * **`disk`** `number` * **`imageName`** `string` * **`memory`** `number` * **`state`** `string` * **`updatedAt`** `object` **Example:** ```json { "name": "", "state": "", "imageName": "", "cpu": 1, "memory": 1, "disk": 1, "createdAt": "", "updatedAt": "" } ``` ### CreateSandboxSnapshotRequest - **Type:**`object` * **`name` (required)** `string` * **`description`** `string` * **`mode`** `string`, possible values: `"scrub_and_delete", "full"`, default: `"scrub_and_delete"` — scrub\_and\_delete (default): remove Amika-injected secrets (credential files + injected env vars) from the sandbox, capture the snapshot from the clean filesystem, then delete the source sandbox. full: capture everything as-is — including secrets — and keep the sandbox running. * **`sandbox_id`** `string` — Source sandbox, by id. * **`sandbox_name`** `string` — Source sandbox, by name. * **`sandbox_ref`** `string` — Source sandbox, by id or name; rejected if both match. **Example:** ```json { "sandbox_id": "", "sandbox_name": "", "sandbox_ref": "", "name": "", "description": "", "mode": "scrub_and_delete" } ``` ### SandboxScrubPreviewResponse - **Type:**`object` * **`env_vars` (required)** `array` **Items:** `string` * **`files` (required)** `array` **Items:** `string` * **`restored_files` (required)** `array` **Items:** `string` **Example:** ```json { "files": [ "" ], "restored_files": [ "" ], "env_vars": [ "" ] } ``` ### SandboxSlackMetadataResponse - **Type:**`object` * **`metadata` (required)** `object` **Example:** ```json { "metadata": { "additionalProperty": { "conversation_id": null, "team_id": "", "team_name": null, "team_icon_url": null, "channel_id": "", "channel_name": null, "thread_id": "", "preview": null, "status": null, "agent_name": "claude" } } } ``` ### CreateSandboxBindingResponse - **Type:**`object` * **`id` (required)** `string` **Example:** ```json { "id": "" } ``` ### CreateSandboxBindingRequest - **Type:** **Example:** ### ListSandboxesResponse - **Type:**`array` **Example:** ### Sandbox - **Type:**`object` * **`amika_opencode_web` (required)** `string | null` * **`branch` (required)** `string | null` * **`commit_hash` (required)** `string | null` * **`created_at` (required)** `object` * **`current_session_id` (required)** `string | null` * **`id` (required)** `string` * **`name` (required)** `string` * **`org_id` (required)** `string` * **`provider` (required)** `string | null` * **`provider_sandbox_id` (required)** `string | null` * **`repo_id` (required)** `string | null` * **`repo_name` (required)** `string | null` * **`repo_provider` (required)** `string | null` * **`repo_url` (required)** `string | null` * **`services` (required)** `array` **Items:** - **`containerPort` (required)** `integer` - **`hostPort` (required)** `integer` - **`name` (required)** `string` - **`protocol` (required)** `string` - **`url` (required)** `string` - **`kind`** `string`, possible values: `"system", "user"` * **`snapshot` (required)** `string | null` * **`updated_at` (required)** `object` * **`user_id` (required)** `string | null` * **`agent_credentials`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`inject_target` (required)** `string | null` - **`kind` (required)** `string` - **`name` (required)** `string | null` - **`scope` (required)** `string | null`, possible values: `"user", "org", null` * **`agent_cwd`** `string | null` * **`created_by`** `object` - **`email` (required)** `string | null` - **`name` (required)** `string | null` * **`error_message`** `string | null` * **`github_auth_mode`** `string | null`, possible values: `"pat", "app_token", null` * **`github_credential_provisioned`** `boolean | null` * **`host_id`** `string | null` * **`mounted_secrets`** `array` **Items:** - **`credential_type` (required)** `string | null`, possible values: `"api_key", "oauth", null` - **`managed` (required)** `boolean` - **`name` (required)** `string` - **`provider` (required)** `string | null` - **`scope` (required)** `string`, possible values: `"user", "org"` * **`origin`** `string | null` * **`resolved_agent_credentials`** `array` **Items:** **One of:** - **`kind` (required)** `string` - **`name` (required)** `string` - **`outcome` (required)** `string`, possible values: `"resolved"` - **`source` (required)** `string` - **`type` (required)** `string`, possible values: `"oauth", "api_key"` * **`kind` (required)** `string` * **`outcome` (required)** `string`, possible values: `"skipped"` * **`reason` (required)** `string`, possible values: `"request:none", "no_user_credential"` * **`sandbox_preset`** `string | null` * **`sandbox_size`** `string | null` * **`sandbox_size_config`** `object` - **`diskGib` (required)** `number` - **`diskGrowOnly` (required)** `boolean` - **`memoryGib` (required)** `number` - **`name` (required)** `string | null` - **`vcpus` (required)** `number` * **`secret_names`** `array` **Items:** `string` * **`setup_status`** `string | null`, possible values: `"ok", "setup-running", "git-failed", "setup-failed", "sys-setup-failed", null` * **`snapshot_name`** `string | null` * **`ssh_key_status`** `string`, possible values: `"ready", "no-key", "stale-keys", "unknown"` * **`state`** `string` * **`status`** `string`, possible values: `"creating", "starting", "running", "stopping", "stopped", "suspending", "suspended", "snapshotting", "failed", "unknown"` * **`urls_expire_at`** `object` **Example:** ```json { "id": "", "user_id": null, "org_id": "", "name": "", "provider": null, "provider_sandbox_id": null, "amika_opencode_web": null, "repo_name": null, "repo_provider": null, "repo_id": null, "repo_url": null, "branch": null, "commit_hash": null, "snapshot": null, "snapshot_name": null, "sandbox_preset": null, "sandbox_size": null, "sandbox_size_config": { "name": null, "vcpus": 1, "memoryGib": 1, "diskGib": 1, "diskGrowOnly": true }, "github_auth_mode": "pat", "github_credential_provisioned": null, "error_message": null, "current_session_id": null, "services": [ { "name": "", "url": "", "hostPort": 1, "containerPort": 1, "protocol": "", "kind": "system" } ], "state": "", "status": "creating", "setup_status": "ok", "urls_expire_at": "", "secret_names": [ "" ], "mounted_secrets": [ { "name": "", "scope": "user", "managed": true, "credential_type": "api_key", "provider": null } ], "resolved_agent_credentials": [ { "kind": "", "outcome": "resolved", "name": "", "type": "oauth", "source": "" } ], "agent_credentials": [ { "kind": "", "name": null, "scope": "user", "credential_type": "api_key", "inject_target": null } ], "created_by": { "name": null, "email": null }, "agent_cwd": null, "ssh_key_status": "ready", "origin": null, "host_id": null, "created_at": "", "updated_at": "" } ``` ### CreateSandboxRequest - **Type:**`object` * **`name` (required)** `string` * **`agent`** `string`, possible values: `"claude", "codex"` * **`agent_credentials`** `array`, default: `[]` **Items:** - **`kind` (required)** `string`, possible values: `"claude", "codex"` - **`name`** `string` - **`none`** `boolean`, possible values: `true` - **`type`** `string`, possible values: `"oauth", "api_key"` * **`amika_opencode_web`** `object` * **`auto_delete_interval`** `number` * **`auto_stop_interval`** `number` * **`branch`** `string` * **`disabled_repo_env_var_names`** `array`, default: `[]` **Items:** `string` * **`env_vars`** `object`, default: `{}` * **`git_url`** `string` * **`github_auth_mode`** `string`, possible values: `"pat", "app_token"` * **`github_url`** `string` * **`host_id`** `string` * **`initial_prompt`** `string` * **`integration_ids`** `array` **Items:** `string` * **`new_branch_name`** `string` * **`preset`** `string`, possible values: `"coder", "coder-plus-docker"` * **`provider`** `string`, possible values: `"daytona", "e2b", "freestyle", "vercel", "smol", "amika-hostd"` * **`repo_url`** `string` * **`resources`** `object` — With \`host\_id\`, the rig's resources, in place of a named \`size\`: 1 to 16 vCPUs, at least 64 MiB of memory in whole MiB, and a disk of at least 1 GiB. Requires \`host\_id\`, and cannot be combined with \`size\`. - **`diskGib` (required)** `integer` - **`memoryGib` (required)** `number` - **`vcpus` (required)** `integer` * **`secret_env_vars`** `object`, default: `{}` * **`setup_script_text`** `string` * **`size`** `string` — Providerless sandbox size (for example \`a0.m\`). Legacy names such as \`m\` and \`medium\` are also accepted. The provider is inferred from \`provider\` or the server default; when omitted, the size defaults to that provider's medium tier. With \`host\_id\`, names one of the host's own sizes instead; a host rig with neither \`size\` nor \`resources\` gets 4 vCPUs, 8 GiB of memory and a 20 GiB disk. * **`skip_setup_script`** `boolean`, default: `false` * **`snapshot`** `string | null` * **`workflow`** `object` - **`enabled` (required)** `boolean` **Example:** ```json { "name": "", "repo_url": "", "git_url": "", "github_url": "", "branch": "", "new_branch_name": "", "provider": "daytona", "host_id": "", "resources": { "vcpus": 1, "memoryGib": 0.0625, "diskGib": 1 }, "auto_stop_interval": 0, "auto_delete_interval": -1, "amika_opencode_web": "", "env_vars": {}, "secret_env_vars": {}, "disabled_repo_env_var_names": [], "setup_script_text": "", "skip_setup_script": false, "agent_credentials": [], "preset": "coder", "size": "", "snapshot": null, "integration_ids": [ "" ], "initial_prompt": "", "agent": "claude", "workflow": { "enabled": true }, "github_auth_mode": "pat" } ``` ### GetSandboxResponse - **Type:** **Example:** ### OkStatus - **Type:**`object` * **`ok` (required)** `boolean`, possible values: `true` **Example:** ```json { "ok": true } ``` ### DirectWebSocketSshSessionResponse - **Type:**`object` * **`connect_credential` (required)** `string` * **`connect_url` (required)** `string`, format: `uri` * **`host_public_key` (required)** `string` * **`sandbox_id` (required)** `string` * **`session_id` (required)** `string` * **`ssh_user` (required)** `string`, possible values: `"amika"` * **`transport` (required)** `string`, possible values: `"direct_ws"` **Example:** ```json { "session_id": "", "transport": "direct_ws", "connect_url": "", "connect_credential": "", "sandbox_id": "", "ssh_user": "amika", "host_public_key": "" } ``` ### TerminalTicketResponse - **Type:**`object` * **`org_id` (required)** `string` * **`ticket` (required)** `string` **Example:** ```json { "ticket": "", "org_id": "" } ``` ### SandboxIntegrationsResponse - **Type:**`array` **Example:** ### SlackConversationResponse - **Type:**`object` * **`conversation` (required)** `object` - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`channel_id` (required)** `string` - **`channel_name` (required)** `string | null` - **`conversation_id` (required)** `string` - **`messages` (required)** `array` **Items:** - **`author` (required)** `string` - **`contents` (required)** `string` - **`direction` (required)** `string`, possible values: `"inbound", "outbound"` - **`id` (required)** `string` - **`is_error` (required)** `boolean` - **`occurred_at` (required)** `object` - **`status` (required)** `string | null` - **`team_id` (required)** `string` - **`team_name` (required)** `string | null` - **`thread_id` (required)** `string` **Example:** ```json { "conversation": { "conversation_id": "", "team_id": "", "team_name": null, "channel_id": "", "channel_name": null, "thread_id": "", "status": null, "agent_name": "claude", "messages": [ { "id": "", "author": "", "direction": "inbound", "contents": "", "occurred_at": "", "is_error": true } ] } } ``` ### AgentSessionsList - **Type:**`object` * **`sessions` (required)** `array` **Items:** - **`agent_name` (required)** `string` - **`created_at` (required)** `object` - **`ended_at` (required)** `object` - **`id` (required)** `string` - **`metadata` (required)** `object` - **`org_id` (required)** `string` - **`sandbox_id` (required)** `string` - **`started_at` (required)** `object` - **`status` (required)** `string` - **`updated_at` (required)** `object` - **`preview`** `string | null` * **`total` (required)** `integer` **Example:** ```json { "sessions": [ { "id": "", "sandbox_id": "", "org_id": "", "agent_name": "", "status": "", "started_at": "", "ended_at": "", "metadata": {}, "preview": null, "created_at": "", "updated_at": "" } ], "total": 0 } ``` ### AgentSession - **Type:**`object` * **`agent_name` (required)** `string` * **`created_at` (required)** `object` * **`ended_at` (required)** `object` * **`id` (required)** `string` * **`metadata` (required)** `object` * **`org_id` (required)** `string` * **`sandbox_id` (required)** `string` * **`started_at` (required)** `object` * **`status` (required)** `string` * **`updated_at` (required)** `object` * **`preview`** `string | null` **Example:** ```json { "id": "", "sandbox_id": "", "org_id": "", "agent_name": "", "status": "", "started_at": "", "ended_at": "", "metadata": {}, "preview": null, "created_at": "", "updated_at": "" } ``` ### CreateSessionRequest - **Type:**`object` * **`agent_name` (required)** `string` * **`metadata`** `object` **Example:** ```json { "agent_name": "", "metadata": {} } ``` ### UpdateSessionRequest - **Type:**`object` * **`metadata`** `object` * **`status`** `string`, possible values: `"active", "completed", "failed"` **Example:** ```json { "status": "active", "metadata": {} } ``` ### WorkflowEventsResponse - **Type:**`object` * **`capped` (required)** `boolean` * **`count` (required)** `integer` * **`events` (required)** `array` **Items:** - **`event_type` (required)** `string` - **`id` (required)** `string` - **`time` (required)** `string` - **`contents`** `object` - **`step`** `string` **Example:** ```json { "events": [ { "event_type": "", "id": "", "time": "", "step": "", "contents": null } ], "count": 1, "capped": true } ``` ### SandboxLifecycleEventsResponse - **Type:**`object` * **`count` (required)** `integer` * **`events` (required)** `array` **Items:** - **`created_at` (required)** `object` - **`detail` (required)** `string | null` - **`id` (required)** `string` - **`run_kind` (required)** `string` - **`status` (required)** `string` - **`step` (required)** `string` **Example:** ```json { "events": [ { "id": "", "run_kind": "", "step": "", "status": "", "detail": null, "created_at": "" } ], "count": 1 } ``` ### SandboxLifecycleEvent - **Type:**`object` * **`created_at` (required)** `object` * **`detail` (required)** `string | null` * **`id` (required)** `string` * **`run_kind` (required)** `string` * **`status` (required)** `string` * **`step` (required)** `string` **Example:** ```json { "id": "", "run_kind": "", "step": "", "status": "", "detail": null, "created_at": "" } ``` ### SandboxServiceInput - **Type:**`object` * **`name` (required)** `string` — Service name: a single DNS label, unique per sandbox. * **`port` (required)** `integer` — Container port the service listens on. * **`url_scheme` (required)** `string`, possible values: `"http", "https"` — URL scheme the gateway serves the service over. **Example:** ```json { "name": "", "port": 1, "url_scheme": "http" } ``` ### SandboxServiceToken - **Type:**`object` * **`expires_at` (required)** `object` * **`header` (required)** `string` — The request header the token goes in, as \`Bearer \\`. * **`token` (required)** `string` * **`url` (required)** `string` — The service's address on the rig's host, ending in \`/\`. It carries no credential. **Example:** ```json { "url": "", "header": "X-Amika-Authorization", "token": "", "expires_at": "" } ``` ### SshPublicKeySummary - **Type:**`object` * **`id` (required)** `string` * **`name` (required)** `string` * **`public_key` (required)** `string` * **`scope` (required)** `string`, possible values: `"user"` **Example:** ```json { "id": "", "name": "", "public_key": "", "scope": "user" } ``` ### UpsertSshPublicKeyRequest - **Type:**`object` * **`name` (required)** `string` * **`public_key` (required)** `string` **Example:** ```json { "name": "", "public_key": "" } ``` ### ListSshPublicKeysResponse - **Type:**`array` **Example:** ### ListSecretsResponse - **Type:**`array` **Example:** ### SecretSummary - **Type:**`object` * **`created_at` (required)** `object` * **`description` (required)** `string | null` * **`id` (required)** `string` * **`name` (required)** `string` * **`org_id` (required)** `string` * **`scope` (required)** `string`, possible values: `"user", "org"` * **`updated_at` (required)** `object` * **`user_id` (required)** `string` **Example:** ```json { "id": "", "org_id": "", "user_id": "", "name": "", "description": null, "scope": "user", "created_at": "", "updated_at": "" } ``` ### CreateSecretRequest - **Type:**`object` * **`name` (required)** `string` * **`value` (required)** `string` * **`description`** `string | null` * **`scope`** `string`, possible values: `"user", "org"` **Example:** ```json { "name": "", "value": "", "scope": "user", "description": null } ``` ### UpdateSecretRequest - **Type:**`object` * **`description`** `string | null` * **`name`** `string` * **`scope`** `string`, possible values: `"user", "org"` * **`value`** `string` **Example:** ```json { "name": "", "value": "", "scope": "user", "description": null } ``` ### ListCredentialsResponse - **Type:**`array` **Example:** ### CreateCredentialRequest - **Type:**`object` * **`name` (required)** `string` * **`type` (required)** `string`, possible values: `"oauth", "api_key"` * **`value` (required)** `string` * **`scope`** `string`, possible values: `"user", "org"` **Example:** ```json { "name": "", "value": "", "type": "oauth", "scope": "user" } ``` ### RevealSecretResponse - **Type:**`object` * **`value` (required)** `string` **Example:** ```json { "value": "" } ``` ### CreateCodexCredentialRequest - **Type:**`object` * **`name` (required)** `string` * **`type` (required)** `string`, possible values: `"oauth", "api_key"` * **`value` (required)** `string` * **`scope`** `string`, possible values: `"user", "org"` **Example:** ```json { "name": "", "value": "", "type": "oauth", "scope": "user" } ``` ### PiStatus - **Type:**`object` * **`configured` (required)** `boolean` * **`secretId`** `string | null` **Example:** ```json { "configured": true, "secretId": null } ``` ### UpsertPiRequest - **Type:**`object` * **`authJson`** `string` * **`source`** `object` - **`agent` (required)** `string`, possible values: `"claude", "codex"` - **`secretId` (required)** `string` **Example:** ```json { "authJson": "", "source": { "agent": "claude", "secretId": "" } } ``` ### ServiceDefinition - **Type:**`object` * **`created_at` (required)** `object` * **`id` (required)** `string` * **`name` (required)** `string` * **`ports` (required)** `array` **Items:** - **`port` (required)** `integer` - **`protocol` (required)** `string` - **`url_scheme` (required)** `string | null` * **`updated_at` (required)** `object` **Example:** ```json { "id": "", "name": "", "ports": [ { "port": 1, "protocol": "", "url_scheme": null } ], "created_at": "", "updated_at": "" } ``` ### SlackOrgSettings - **Type:**`object` * **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` * **`created_at` (required)** `object` * **`org_id` (required)** `string` * **`repository_id` (required)** `string | null` * **`system_prompt` (required)** `string | null` * **`updated_at` (required)** `object` **Example:** ```json { "org_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ``` ### SlackOrgSettingsUpsert - **Type:**`object` * **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` * **`repository_id` (required)** `string | null` * **`system_prompt` (required)** `string | null` **Example:** ```json { "repository_id": null, "agent_name": "claude", "system_prompt": null } ``` ### SlackChannelSettingsList - **Type:**`object` * **`seen_channels` (required)** `array` **Items:** - **`last_seen_at` (required)** `object` - **`slack_channel_id` (required)** `string` - **`slack_channel_name` (required)** `string | null` - **`slack_team_id` (required)** `string` - **`slack_team_name` (required)** `string | null` * **`settings` (required)** `array` **Items:** - **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` - **`created_at` (required)** `object` - **`org_id` (required)** `string` - **`repository_id` (required)** `string | null` - **`slack_channel_id` (required)** `string` - **`slack_team_id` (required)** `string` - **`system_prompt` (required)** `string | null` - **`updated_at` (required)** `object` **Example:** ```json { "settings": [ { "org_id": "", "slack_team_id": "", "slack_channel_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ], "seen_channels": [ { "slack_team_id": "", "slack_team_name": null, "slack_channel_id": "", "slack_channel_name": null, "last_seen_at": "" } ] } ``` ### SlackChannelSettings - **Type:**`object` * **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` * **`created_at` (required)** `object` * **`org_id` (required)** `string` * **`repository_id` (required)** `string | null` * **`slack_channel_id` (required)** `string` * **`slack_team_id` (required)** `string` * **`system_prompt` (required)** `string | null` * **`updated_at` (required)** `object` **Example:** ```json { "org_id": "", "slack_team_id": "", "slack_channel_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ``` ### SlackSeenChannel - **Type:**`object` * **`last_seen_at` (required)** `object` * **`slack_channel_id` (required)** `string` * **`slack_channel_name` (required)** `string | null` * **`slack_team_id` (required)** `string` * **`slack_team_name` (required)** `string | null` **Example:** ```json { "slack_team_id": "", "slack_team_name": null, "slack_channel_id": "", "slack_channel_name": null, "last_seen_at": "" } ``` ### SlackChannelSettingsUpsert - **Type:**`object` * **`slack_channel_id` (required)** `string` * **`slack_team_id` (required)** `string` * **`agent_name`** `string | null`, possible values: `"claude", "codex", null` * **`repository_id`** `string | null` * **`system_prompt`** `string | null` **Example:** ```json { "slack_team_id": "", "slack_channel_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null } ``` ### SlackChannelSettingsDelete - **Type:**`object` * **`slack_channel_id` (required)** `string` * **`slack_team_id` (required)** `string` **Example:** ```json { "slack_team_id": "", "slack_channel_id": "" } ``` ### LinearOrgSettings - **Type:**`object` * **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` * **`created_at` (required)** `object` * **`org_id` (required)** `string` * **`repository_id` (required)** `string | null` * **`system_prompt` (required)** `string | null` * **`updated_at` (required)** `object` **Example:** ```json { "org_id": "", "repository_id": null, "agent_name": "claude", "system_prompt": null, "created_at": "", "updated_at": "" } ``` ### LinearOrgSettingsUpsert - **Type:**`object` * **`agent_name` (required)** `string | null`, possible values: `"claude", "codex", null` * **`repository_id` (required)** `string | null` * **`system_prompt` (required)** `string | null` **Example:** ```json { "repository_id": null, "agent_name": "claude", "system_prompt": null } ``` ### UploadResponse - **Type:**`object` * **`bucket` (required)** `string` * **`expires_in` (required)** `integer` * **`path` (required)** `string` * **`token` (required)** `string` * **`upload_url` (required)** `string` **Example:** ```json { "bucket": "", "path": "", "upload_url": "", "token": "", "expires_in": 1 } ``` ### CreateUploadRequest - **Type:**`object` * **`filename` (required)** `string` * **`upsert`** `boolean`, default: `false` **Example:** ```json { "filename": "", "upsert": false } ``` ### UploadBatchResponse - **Type:**`object` * **`bucket` (required)** `string` * **`expires_in` (required)** `integer` * **`objects` (required)** `array` **Items:** - **`path` (required)** `string` - **`token` (required)** `string` - **`upload_url` (required)** `string` **Example:** ```json { "bucket": "", "objects": [ { "path": "", "upload_url": "", "token": "" } ], "expires_in": 1 } ``` ### CreateUploadBatchRequest - **Type:**`object` * **`files` (required)** `array` **Items:** - **`filename` (required)** `string` - **`upsert`** `boolean`, default: `false` **Example:** ```json { "files": [ { "filename": "", "upsert": false } ] } ``` ### ListDownloadsResponse - **Type:**`object` * **`bucket` (required)** `string` * **`expires_in` (required)** `integer` * **`next_cursor` (required)** `string | null` * **`objects` (required)** `array` **Items:** - **`download_url` (required)** `string` - **`key` (required)** `string` - **`last_modified`** `string` - **`size`** `integer` * **`prefix` (required)** `string` **Example:** ```json { "bucket": "", "prefix": "", "objects": [ { "key": "", "size": 1, "last_modified": "", "download_url": "" } ], "expires_in": 1, "next_cursor": null } ``` ### DownloadObject - **Type:**`object` * **`download_url` (required)** `string` * **`key` (required)** `string` * **`last_modified`** `string` * **`size`** `integer` **Example:** ```json { "key": "", "size": 1, "last_modified": "", "download_url": "" } ``` ### DownloadResponse - **Type:**`object` * **`bucket` (required)** `string` * **`download_url` (required)** `string` * **`expires_in` (required)** `integer` * **`path` (required)** `string` **Example:** ```json { "bucket": "", "path": "", "download_url": "", "expires_in": 1 } ``` ### CreateDownloadRequest - **Type:**`object` * **`filename` (required)** `string` * **`download`** `boolean`, default: `false` **Example:** ```json { "filename": "", "download": false } ```