{ "openapi": "3.1.0", "info": { "title": "Bernstein Task Server", "description": "Bernstein REST API — multi-agent orchestration for CLI coding agents.\n\n## Authentication\n\nWhen auth is enabled (`BERNSTEIN_AUTH_ENABLED=true`), include a Bearer token in all requests:\n\n```\nAuthorization: Bearer \n```\n\nPublic endpoints (no auth required): `/health`, `/health/ready`, `/health/live`, `/.well-known/agent.json`, `/docs`, `/openapi.json`.\n\n## Base URL\n\nDefault: `http://127.0.0.1:8052`. Override with env vars `BERNSTEIN_HOST` and `BERNSTEIN_PORT`.\n\n## Error Format\n\nAll errors return JSON with a `detail` field:\n\n```json\n{\"detail\": \"Task not found: task-xyz\"}\n```\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Bad request (validation error) |\n| 401 | Unauthorized (missing/invalid token) |\n| 403 | Forbidden (IP not in allowlist) |\n| 404 | Resource not found |\n| 409 | Conflict (task already in terminal state) |\n| 429 | Rate limited — respect the `Retry-After` header |\n| 500 | Internal server error |\n", "version": "1.0.0" }, "paths": { "/": { "get": { "summary": "Root", "operationId": "root__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Root Get" } } } } } } }, "/tasks/search": { "get": { "summary": "Search Tasks", "description": "Search tasks with pagination, sorting, and filtering.\n\nQuery params:\n page: Page number (1-based, default 1).\n per_page: Items per page (1-100, default 20).\n sort: Sort field (created_at, priority, title, role, status).\n order: Sort order (asc, desc; default desc).\n status: Filter by task status.\n role: Filter by task role.\n assigned_agent: Filter by assigned agent.", "operationId": "search_tasks_tasks_search_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "title": "Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Per Page" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at", "title": "Sort" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Order" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "role", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" } }, { "name": "assigned_agent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{session_id}/logs": { "get": { "summary": "Agent Logs", "description": "Return log file content for a session.\n\nArgs:\n session_id: Agent session ID.\n tail_bytes: If > 0, return only the last N bytes of the log.", "operationId": "agent_logs_agents__session_id__logs_get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "tail_bytes", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Tail Bytes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "description": "No log file for session" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{session_id}/kill": { "post": { "summary": "Agent Kill", "description": "Request that an agent session be killed.\n\nWrites a ``.kill`` signal file that the orchestrator picks up on\nits next tick.", "operationId": "agent_kill_agents__session_id__kill_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{session_id}/stream": { "get": { "summary": "Agent Stream", "description": "SSE stream of live log output for a session.", "operationId": "agent_stream_agents__session_id__stream_get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/providers": { "get": { "tags": [ "authentication" ], "summary": "Auth Providers", "description": "List available authentication providers.", "operationId": "auth_providers_auth_providers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthProvidersResponse" } } } } } } }, "/auth/login": { "get": { "tags": [ "authentication" ], "summary": "Login", "description": "Initiate SSO login. Redirects to IdP.", "operationId": "login_auth_login_get", "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "default": "oidc", "title": "Provider" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Authentication provider not enabled" }, "503": { "description": "SSO authentication not configured" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/oidc/callback": { "get": { "tags": [ "authentication" ], "summary": "Oidc Callback", "description": "OIDC authorization code callback.", "operationId": "oidc_callback_auth_oidc_callback_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Missing or invalid authorization code or state" }, "503": { "description": "SSO authentication not configured" } } } }, "/auth/saml/acs": { "post": { "tags": [ "authentication" ], "summary": "Saml Acs", "description": "SAML Assertion Consumer Service (ACS) endpoint.\n\nReceives the SAML Response from the IdP via HTTP-POST binding.", "operationId": "saml_acs_auth_saml_acs_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Missing SAMLResponse" }, "503": { "description": "SSO authentication not configured" } } } }, "/auth/saml/metadata": { "get": { "tags": [ "authentication" ], "summary": "Saml Metadata", "description": "SAML SP metadata endpoint for IdP configuration.", "operationId": "saml_metadata_auth_saml_metadata_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "503": { "description": "SSO authentication not configured" } } } }, "/auth/cli/device": { "post": { "tags": [ "authentication" ], "summary": "Device Code Request", "description": "Initiate device authorization flow for CLI login.\n\nThe CLI calls this to get a device_code and user_code.\nThe user enters the user_code in the web dashboard after SSO login\nto authorize the CLI session.", "operationId": "device_code_request_auth_cli_device_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCodeResponse" } } } }, "503": { "description": "SSO authentication not configured" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/cli/token": { "post": { "tags": [ "authentication" ], "summary": "Device Token Poll", "description": "Poll for device authorization status.\n\nReturns the access token once the user has authorized the device code.", "operationId": "device_token_poll_auth_cli_token_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePollRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePollResponse" } } } }, "503": { "description": "SSO authentication not configured" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/cli/authorize": { "post": { "tags": [ "authentication" ], "summary": "Device Authorize", "description": "Authorize a device code (called from web dashboard after SSO login).\n\nRequires an authenticated user session.", "operationId": "device_authorize_auth_cli_authorize_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizeRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid or expired user code" }, "401": { "description": "Authentication required" }, "503": { "description": "SSO authentication not configured" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/me": { "get": { "tags": [ "authentication" ], "summary": "Get Profile", "description": "Get the current authenticated user's profile.", "operationId": "get_profile_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" } } } }, "401": { "description": "Authentication required" } } } }, "/auth/logout": { "post": { "tags": [ "authentication" ], "summary": "Logout", "description": "Logout and revoke the current session.", "operationId": "logout_auth_logout_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "503": { "description": "SSO authentication not configured" } } } }, "/auth/group-mappings": { "get": { "tags": [ "authentication" ], "summary": "Get Group Mappings", "description": "Get current SSO group → role mappings.", "operationId": "get_group_mappings_auth_group_mappings_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMappingsResponse" } } } }, "503": { "description": "SSO authentication not configured" } } }, "put": { "tags": [ "authentication" ], "summary": "Update Group Mappings", "description": "Update SSO group → role mappings (admin only).", "operationId": "update_group_mappings_auth_group_mappings_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMappingsUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid role value" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin role required" }, "503": { "description": "SSO authentication not configured" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/users": { "get": { "tags": [ "authentication" ], "summary": "List Users", "description": "List all users (admin only).", "operationId": "list_users_auth_users_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required" }, "403": { "description": "Admin role required" }, "503": { "description": "SSO authentication not configured" } } } }, "/tasks": { "post": { "summary": "Create Task", "description": "Create a new task.", "operationId": "create_task_tasks_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "description": "Blocked by pre-create hook" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "List Tasks", "description": "List tasks, optionally filtered by status, cell_id, and/or claim owner.\n\nWhen ``limit`` or ``offset`` query params are provided the response is a\npaginated envelope (``{tasks, total, limit, offset}``). Without them,\nthe legacy flat list is returned for backward compatibility.\n\nArgs:\n request: FastAPI request.\n status: If provided, only tasks with this status are returned.\n cell_id: If provided, only tasks in this cell are returned.\n tenant: Tenant scope override.\n claimed_by_session: If provided, only tasks claimed by this parent\n orchestrator session are returned.\n limit: Maximum number of tasks to return (max 500). Triggers\n paginated response when present.\n offset: Number of tasks to skip. Triggers paginated response\n when present.\n\nReturns:\n Paginated response **or** plain list of TaskResponse dicts.", "operationId": "list_tasks_tasks_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "cell_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cell Id" } }, { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } }, { "name": "claimed_by_session", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claimed By Session" } }, { "name": "parent_session_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Session Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PaginatedTasksResponse" }, { "type": "array", "items": { "$ref": "#/components/schemas/TaskResponse" } } ], "title": "Response List Tasks Tasks Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/batch": { "post": { "summary": "Create Tasks Batch", "description": "Create multiple tasks atomically with title dedup.", "operationId": "create_tasks_batch_tasks_batch_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateResponse" } } } }, "503": { "description": "Server is draining" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/self-create": { "post": { "summary": "Self Create Subtask", "description": "Create a subtask linked to a parent task.\n\nAgents call this to decompose work during execution. The parent\ntask is automatically transitioned to ``WAITING_FOR_SUBTASKS`` on\nthe first subtask creation (if it is not already in that state).", "operationId": "self_create_subtask_tasks_self_create_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSelfCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Parent task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/next/{role}": { "get": { "summary": "Next Task", "description": "Claim the next available task for *role*.\n\nPass ``claimed_by_session`` as a query param to record which parent\norchestrator session owns the claim.\n\nPass ``parent_session_id`` to restrict claiming to tasks that were\ncreated under that coordinator session. Workers belonging to a\ncoordinator should always pass their coordinator's session ID here\nto avoid stealing tasks from other namespaces.", "operationId": "next_task_tasks_next__role__get", "parameters": [ { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "title": "Role" } }, { "name": "claimed_by_session", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claimed By Session" } }, { "name": "parent_session_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "No open tasks for role" }, "503": { "description": "Server is draining" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/claim-batch": { "post": { "summary": "Claim Batch", "description": "Atomically claim multiple tasks by ID for an agent.", "operationId": "claim_batch_tasks_claim_batch_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchClaimRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchClaimResponse" } } } }, "503": { "description": "Server is draining" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/claim": { "post": { "summary": "Claim Task", "description": "Claim a specific task by ID.\n\nPass ``expected_version`` as a query param for optimistic locking\n(CAS). If the task's version doesn't match, returns 409 Conflict.\n\nPass ``claimed_by_session`` to record which parent orchestrator\nsession owns this claim.", "operationId": "claim_task_tasks__task_id__claim_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "expected_version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expected Version" } }, { "name": "claimed_by_session", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claimed By Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Version conflict or invalid state" }, "503": { "description": "Server is draining" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/complete": { "post": { "summary": "Complete Task", "description": "Mark a task as done with a result summary.", "operationId": "complete_task_tasks__task_id__complete_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCompleteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/wait-for-subtasks": { "post": { "summary": "Wait For Subtasks", "description": "Mark a parent task as waiting until its generated subtasks complete.", "operationId": "wait_for_subtasks_tasks__task_id__wait_for_subtasks_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskWaitForSubtasksRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/fail": { "post": { "summary": "Fail Task", "description": "Mark a task as failed.", "operationId": "fail_task_tasks__task_id__fail_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskFailRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/close": { "post": { "summary": "Close Task", "description": "Mark a verified task as closed (terminal success state).", "operationId": "close_task_tasks__task_id__close_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/cancel": { "post": { "summary": "Cancel Task", "description": "Cancel a task that has not yet finished.", "operationId": "cancel_task_tasks__task_id__cancel_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCancelRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/block": { "post": { "summary": "Block Task", "description": "Mark a task as blocked -- requires human intervention to unblock.", "operationId": "block_task_tasks__task_id__block_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskBlockRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/progress": { "post": { "summary": "Progress Task", "description": "Append an intermediate progress update to a task.\n\nAlso stores a progress snapshot for stall detection when snapshot\nfields (files_changed, tests_passing, errors) are provided.", "operationId": "progress_task_tasks__task_id__progress_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskProgressRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/snapshots": { "get": { "summary": "Get Task Snapshots", "description": "Return stored progress snapshots for a task (oldest-first, up to 10).", "operationId": "get_task_snapshots_tasks__task_id__snapshots_get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SnapshotEntry" }, "title": "Response Get Task Snapshots Tasks Task Id Snapshots Get" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/counts": { "get": { "summary": "Task Counts", "description": "Return task counts per status without serialising task bodies.\n\nThis is the lightweight alternative to GET /tasks for orchestrator\ntick summaries and dashboard polling.", "operationId": "task_counts_tasks_counts_get", "parameters": [ { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCountsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/archive": { "get": { "summary": "Get Archive", "description": "Return the last N archived (done/failed) task records.", "operationId": "get_archive_tasks_archive_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArchiveRecord" }, "title": "Response Get Archive Tasks Archive Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/graph": { "get": { "summary": "Get Task Graph", "description": "Return the task dependency graph as JSON (nodes + edges + critical path).\n\nBuilds a DAG from all current tasks and returns:\n- ``nodes``: list of {id, role, status, estimated_minutes, title}\n- ``edges``: list of {from, to, type, semantic_type}\n- ``critical_path``: ordered list of task IDs on the longest chain\n- ``critical_path_minutes``: total estimated minutes on the critical path\n- ``parallel_width``: max tasks that can run concurrently\n- ``bottlenecks``: task IDs that block the most downstream work", "operationId": "get_task_graph_tasks_graph_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/tasks/{task_id}": { "get": { "summary": "Get Task", "description": "Get a single task by ID.", "operationId": "get_task_tasks__task_id__get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "summary": "Patch Task", "description": "Update mutable task fields (role, priority, model) — manager corrections.\n\nUsed by the manager agent or dashboard to correct mis-assigned tasks,\nadjust priority, or change model without interrupting the orchestrator.", "operationId": "patch_task_tasks__task_id__patch", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskPatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/gates": { "get": { "summary": "Get Task Gates", "description": "Return the persisted quality-gate report for a task.", "operationId": "get_task_gates_tasks__task_id__gates_get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Task or gate report not found" }, "500": { "description": "Gate report unreadable" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/prioritize": { "post": { "summary": "Prioritize Task", "description": "Bump a task to priority 0 so the orchestrator picks it up next.", "operationId": "prioritize_task_tasks__task_id__prioritize_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tasks/{task_id}/force-claim": { "post": { "summary": "Force Claim Task", "description": "Force a task back to open with priority 0 for immediate pickup.\n\nResets claimed/in_progress tasks back to open so the orchestrator's\nnext tick will spawn a fresh agent for them. Terminal tasks\n(done/failed/cancelled) are rejected with 409.", "operationId": "force_claim_task_tasks__task_id__force_claim_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Cannot force-claim terminal task" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/heartbeat": { "post": { "summary": "Agent Heartbeat", "description": "Register an agent heartbeat.", "operationId": "agent_heartbeat_agents__agent_id__heartbeat_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bulletin": { "post": { "summary": "Post Bulletin", "description": "Append a message to the bulletin board.", "operationId": "post_bulletin_bulletin_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulletinPostRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulletinMessageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "Get Bulletin", "description": "Get bulletin messages since a given timestamp.", "operationId": "get_bulletin_bulletin_get", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "number", "default": 0.0, "title": "Since" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BulletinMessageResponse" }, "title": "Response Get Bulletin Bulletin Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/.well-known/agent.json": { "get": { "summary": "Agent Card", "description": "Publish the Bernstein orchestrator Agent Card (A2A spec).", "operationId": "agent_card__well_known_agent_json_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AAgentCardResponse" } } } } } } }, "/a2a/agents": { "get": { "summary": "List A2A Agents", "description": "Return Bernstein's A2A agent card via the task API namespace.", "operationId": "list_a2a_agents_a2a_agents_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AAgentCardResponse" } } } } } } }, "/a2a/message": { "post": { "summary": "A2A Message", "description": "Receive an inbound A2A message and inject it into the target task context.", "operationId": "a2a_message_a2a_message_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AMessageRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AMessageResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/a2a/tasks/send": { "post": { "summary": "A2A Send Task", "description": "Receive a task from an external A2A agent.\n\nCreates both an A2A task record and a corresponding Bernstein task,\nlinking them together for lifecycle synchronisation.", "operationId": "a2a_send_task_a2a_tasks_send_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ATaskSendRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ATaskResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/a2a/tasks/{a2a_task_id}": { "get": { "summary": "A2A Get Task", "description": "Get an A2A task by ID, syncing status from the Bernstein task.", "operationId": "a2a_get_task_a2a_tasks__a2a_task_id__get", "parameters": [ { "name": "a2a_task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "A2A Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ATaskResponse" } } } }, "404": { "description": "A2A task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/a2a/tasks/{a2a_task_id}/artifacts": { "post": { "summary": "A2A Add Artifact", "description": "Attach an artifact to an A2A task.", "operationId": "a2a_add_artifact_a2a_tasks__a2a_task_id__artifacts_post", "parameters": [ { "name": "a2a_task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "A2A Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AArtifactRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AArtifactResponse" } } } }, "404": { "description": "A2A task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/cluster/nodes": { "post": { "summary": "Register Node", "description": "Register a new node in the cluster.", "operationId": "register_node_cluster_nodes_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeRegisterRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "List Nodes", "description": "List all cluster nodes, optionally filtered by status.", "operationId": "list_nodes_cluster_nodes_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NodeResponse" }, "title": "Response List Nodes Cluster Nodes Get" } } } }, "400": { "description": "Invalid node status" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/cluster/nodes/{node_id}/heartbeat": { "post": { "summary": "Node Heartbeat", "description": "Record a heartbeat from a cluster node.", "operationId": "node_heartbeat_cluster_nodes__node_id__heartbeat_post", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeHeartbeatRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeResponse" } } } }, "404": { "description": "Node not registered" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/cluster/nodes/{node_id}": { "delete": { "summary": "Unregister Node", "description": "Remove a node from the cluster.", "operationId": "unregister_node_cluster_nodes__node_id__delete", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "responses": { "204": { "description": "Successful Response" }, "404": { "description": "Node not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/cluster/nodes/{node_id}/cordon": { "post": { "summary": "Cordon Node", "description": "Cordon a node -- exclude from scheduling.", "operationId": "cordon_node_cluster_nodes__node_id__cordon_post", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Cordon Node Cluster Nodes Node Id Cordon Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/cluster/nodes/{node_id}/uncordon": { "post": { "summary": "Uncordon Node", "description": "Uncordon a node -- resume accepting tasks.", "operationId": "uncordon_node_cluster_nodes__node_id__uncordon_post", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Uncordon Node Cluster Nodes Node Id Uncordon Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/cluster/nodes/{node_id}/drain": { "post": { "summary": "Drain Node", "description": "Start draining a node -- cordon + signal agents to finish.", "operationId": "drain_node_cluster_nodes__node_id__drain_post", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Drain Node Cluster Nodes Node Id Drain Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/cluster/status": { "get": { "summary": "Cluster Status", "description": "Get cluster status summary.", "operationId": "cluster_status_cluster_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterStatusResponse" } } } } } } }, "/cluster/steal": { "post": { "summary": "Steal Tasks", "description": "Evaluate task stealing policy and reassign claimed tasks between nodes.\n\nWorkers report their queue depths; the server runs the steal policy and\nreturns a list of task reassignments. Stolen tasks are reset to ``open``\nso the receiver node can claim them.", "operationId": "steal_tasks_cluster_steal_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStealRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStealResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/status": { "get": { "summary": "Status Dashboard", "description": "Dashboard summary of task counts.", "operationId": "status_dashboard_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/status/duration-predictions": { "get": { "summary": "Duration Predictions", "description": "Return ML-predicted duration estimates for all open/claimed tasks.\n\nUses the local GradientBoosting duration predictor. Falls back to the\nstatic cold-start table when fewer than 50 completions are available.\n\nResponse shape::\n\n {\n \"predictor\": {\n \"trained\": true,\n \"training_samples\": 142,\n \"cold_start\": false\n },\n \"tasks\": [\n {\n \"task_id\": \"abc123\",\n \"title\": \"Refactor auth module\",\n \"role\": \"backend\",\n \"p50_seconds\": 720.0,\n \"p90_seconds\": 1440.0,\n \"confidence\": 0.62,\n \"is_cold_start\": false,\n \"eta_p50\": \"12m 0s\",\n \"eta_p90\": \"24m 0s\"\n }\n ]\n }", "operationId": "duration_predictions_status_duration_predictions_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/routing/bandit": { "get": { "summary": "Bandit Routing Stats", "description": "Return contextual bandit routing statistics.\n\nReads persisted state from ``.sdd/routing/``. Returns an empty dict\nwhen bandit routing has not been activated (``--routing bandit`` not passed).", "operationId": "bandit_routing_stats_routing_bandit_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health": { "get": { "summary": "Health Check", "description": "Liveness check with component-level status.", "operationId": "health_check_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/health/ready": { "get": { "summary": "Ready Check", "description": "Readiness check for load balancers.", "operationId": "ready_check_health_ready_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/ready": { "get": { "summary": "Ready Alias", "description": "Alias for /health/ready.", "operationId": "ready_alias_ready_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health/live": { "get": { "summary": "Live Check", "description": "Liveness check for process monitoring.", "operationId": "live_check_health_live_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/alive": { "get": { "summary": "Live Alias", "description": "Alias for /health/live.", "operationId": "live_alias_alive_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/config": { "post": { "summary": "Update Config", "description": "Update mutable config fields at runtime.\n\nAccepts JSON body with ``{\"max_agents\": N}``. Writes the change to\n``bernstein.yaml`` so the orchestrator's hot-reload picks it up on\nthe next tick (~30s). Returns the new effective value.", "operationId": "update_config_config_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/shutdown": { "post": { "summary": "Shutdown Server", "description": "Initiate graceful server shutdown.\n\nAccepts an optional JSON body ``{\"reason\": \"...\"}``. Schedules a\nSIGTERM to the current process shortly after the response is sent so\nthat the Uvicorn server exits cleanly.", "operationId": "shutdown_server_shutdown_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/cache-stats": { "get": { "summary": "Cache Stats", "description": "Return prompt caching statistics from the manifest.\n\nReads `.sdd/caching/manifest.jsonl` and returns aggregated counts,\nestimated token savings, and estimated USD savings based on the\nAnthropic cached-input discount (90% off standard input price).\n\nReturns 200 with empty statistics if no cache manifest exists yet.", "operationId": "cache_stats_cache_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/metrics": { "get": { "summary": "Metrics Endpoint", "description": "Prometheus metrics scrape endpoint.\n\nUpdates all gauges from the current task store state, then\nreturns the full metric exposition in Prometheus text format.", "operationId": "metrics_endpoint_metrics_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/dashboard": { "get": { "summary": "Dashboard Page", "description": "Serve the single-page web dashboard.", "operationId": "dashboard_page_dashboard_get", "responses": { "200": { "description": "Successful Response", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/dashboard/data": { "get": { "summary": "Dashboard Data", "description": "Return all mission control dashboard data as JSON.\n\nIncludes stats, tasks with timeline data, agent details with costs,\nfile ownership map, cost history, and alerts.", "operationId": "dashboard_data_dashboard_data_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/memory/audit": { "get": { "summary": "Memory Audit", "description": "Audit the lesson memory provenance chain (OWASP ASI06 2026).\n\nReturns chain integrity status and a per-entry provenance trail.\nDetects tampering, insertion, deletion, and reordering attacks.", "operationId": "memory_audit_memory_audit_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/broadcast": { "post": { "summary": "Broadcast Command", "description": "Send a message to all running agents via fastest available channel.\n\nUses stdin pipe where available (sub-second delivery), falls back\nto file-based COMMAND signal for agents without pipe support.\n\nExpects JSON body: ``{\"message\": \"some instruction\"}``.", "operationId": "broadcast_command_broadcast_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/events": { "get": { "summary": "Sse Events", "description": "Server-Sent Events stream for real-time dashboard updates.\n\nIncludes disconnect detection via heartbeat pings and connection\ntimeout handling to prevent leaked subscriber queues.", "operationId": "sse_events_events_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/badge.json": { "get": { "summary": "Get Badge", "description": "Return dynamic badge data for GitHub shields.io integration.\n\nShows tasks completed, total cost, and quality score.\nUsage: https://img.shields.io/endpoint?url=/badge.json", "operationId": "get_badge_badge_json_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/workspace": { "get": { "tags": [ "workspace" ], "summary": "Workspace Status", "description": "Return repository status for the configured workspace.", "operationId": "workspace_status_workspace_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "400": { "description": "Invalid seed file" } } } }, "/workspace/merge-order": { "post": { "tags": [ "workspace" ], "summary": "Workspace Merge Order", "description": "Return the repo merge order derived from current cross-repo task dependencies.", "operationId": "workspace_merge_order_workspace_merge_order_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeOrderResponse" } } } }, "400": { "description": "Invalid seed file" }, "404": { "description": "No workspace configured" } } } }, "/alerts": { "get": { "summary": "Get Alerts", "description": "Return current dashboard alerts as JSON.\n\nBuilds alerts from the live task/agent state — failed tasks, blocked\ntasks, stale agents, and budget thresholds. Intended for dashboard\npolling or external monitoring.\n\nReturns a JSON object with keys:\n- ``alerts``: list of alert dicts (``level``, ``message``, ``detail``)\n- ``count``: total number of alerts\n- ``ts``: server timestamp (Unix seconds)", "operationId": "get_alerts_alerts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/webhook": { "post": { "summary": "Generic Webhook", "description": "Create a task directly from a generic inbound webhook payload.\n\nThe endpoint is intentionally small and separate from the trigger-manager\nflow: callers POST a task-shaped payload and Bernstein creates one task.\nWhen ``BERNSTEIN_WEBHOOK_SECRET`` is configured, callers must also send\nthe same value in ``X-Bernstein-Webhook-Secret``.", "operationId": "generic_webhook_webhook_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTaskCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTaskResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/github": { "post": { "summary": "Github Webhook", "description": "Receive a GitHub App webhook, verify signature, and create tasks.\n\nHandles the following event types:\n- ``issues`` (opened / labeled)\n- ``pull_request_review_comment`` / ``issue_comment``\n- ``push``\n- ``workflow_run`` (completed + failure) — creates a ci-fix task, capped at\n ``MAX_CI_RETRIES`` active attempts per branch.\n\nReads ``GITHUB_WEBHOOK_SECRET`` from environment for HMAC verification.\nReturns 200 on success, 401 on bad/missing signature, 400 on parse error.", "operationId": "github_webhook_webhooks_github_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/webhooks/gitlab": { "post": { "summary": "Gitlab Webhook", "description": "Receive a GitLab CI webhook, verify token, and create ci-fix tasks.\n\nHandles the following event types:\n- ``pipeline`` (failed) — creates a ci-fix task, capped at\n ``MAX_CI_RETRIES`` active attempts per branch.\n- ``job`` (failed) — creates a ci-fix task for the specific job.\n\nReads ``GITLAB_WEBHOOK_TOKEN`` from environment. GitLab sends a simple\nplaintext token in the ``x-gitlab-token`` header.\nReturns 200 on success, 401 on bad/missing token.", "operationId": "gitlab_webhook_webhooks_gitlab_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/webhooks/discord/interactions": { "post": { "summary": "Discord Interactions", "description": "Receive and route Discord Application Command interactions.\n\nVerifies the Ed25519 signature, handles PING handshakes, and dispatches\nslash commands to the appropriate handler. Returns an immediate response\n(Discord requires a reply within 3 seconds).\n\nReturns:\n 200 with a Discord interaction response object on success.\n 401 if the signature is invalid.\n 400 if the payload cannot be parsed.", "operationId": "discord_interactions_webhooks_discord_interactions_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/webhooks/slack/commands": { "post": { "summary": "Slack Slash Command", "description": "Receive a Slack slash command, verify signature, and ack immediately.\n\nSlack requires a response within 3 seconds. This endpoint verifies the\nrequest signature, parses the URL-encoded form payload, and returns an\nimmediate acknowledgement. Any long-running work (task creation, etc.)\nshould be dispatched asynchronously using ``response_url``.\n\nReads ``SLACK_SIGNING_SECRET`` from environment for HMAC verification.\nReturns 200 on success, 401 on bad/missing signature, 400 on parse error.\n\nSlash command form fields parsed:\n - ``command`` — the slash command (e.g. ``/bernstein``)\n - ``text`` — text following the command\n - ``user_id`` — Slack user ID\n - ``channel_id`` — Slack channel ID\n - ``response_url`` — URL for delayed responses (up to 30 min)\n - ``trigger_id`` — trigger ID for opening modals", "operationId": "slack_slash_command_webhooks_slack_commands_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/webhooks/slack/events": { "post": { "summary": "Slack Events", "description": "Receive Slack Events API callbacks.\n\nHandles:\n- ``url_verification``: returns the challenge value for endpoint verification.\n- ``event_callback`` with ``message`` type: creates a task when the bot is\n mentioned. Bot messages and ``message_changed`` subtypes are ignored to\n prevent loops.\n\nReads ``SLACK_SIGNING_SECRET`` from environment for HMAC verification.\nReturns 200 on success, 401 on bad/missing signature, 400 on parse error.", "operationId": "slack_events_webhooks_slack_events_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/events/cost": { "get": { "summary": "Cost Events", "description": "SSE endpoint for real-time cost updates.\n\nListens to the global SSE bus for ``bulletin`` events that match\nthe ``live_cost_update`` status pattern and forwards them to clients.\nAlso provides periodic heartbeats.", "operationId": "cost_events_events_cost_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/costs": { "get": { "summary": "Get Costs", "description": "Aggregate cost data across all runs.\n\nScans every persisted cost file in ``.sdd/runtime/costs/``, aggregates\nper-agent and per-model totals, and computes cost attainment as\n``(total_spent / total_budget) * 100``. Budget of zero is treated as\nunlimited — attainment is reported as 0.0 in that case.", "operationId": "get_costs_costs_get", "parameters": [ { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Tenant access denied" }, "404": { "description": "Tenant not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/costs/live": { "get": { "summary": "Get Cost Live", "description": "Return live cost breakdown for the most recent run.\n\nFinds the most recently modified cost file in ``.sdd/runtime/costs/``,\nloads it, and returns budget status plus per-agent and per-model\ncost breakdowns.", "operationId": "get_cost_live_costs_live_get", "parameters": [ { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Tenant access denied" }, "404": { "description": "Tenant not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/costs/current": { "get": { "summary": "Get Cost Current", "description": "Return real-time cost snapshot for the active run.\n\nUpdated after each agent completion. Designed for TUI sidebar polling\nand lightweight dashboard widgets. Returns per-model input/output/cache\ntoken breakdown alongside spend and budget status.", "operationId": "get_cost_current_costs_current_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/costs/alerts": { "get": { "summary": "Get Cost Alerts", "description": "Return active budget alerts and 30d/90d cost trends.\n\nReads the live cost data for the most recent run, checks whether spend\nhas reached the 80% or 95% alert threshold, and returns trend data\ncomputed from ``.sdd/metrics/cost_history.jsonl``.", "operationId": "get_cost_alerts_costs_alerts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/costs/history": { "get": { "summary": "Get Cost History", "description": "Return daily cost history with burn rate for chart visualization.\n\nLoads daily snapshots from ``.sdd/metrics/cost_history.jsonl`` and computes\na burn rate from the most recent 7 days. Burn rate is expressed both as\nUSD/day (7-day trailing average) and USD/hour.", "operationId": "get_cost_history_costs_history_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/costs/{run_id}": { "get": { "summary": "Get Cost Budget", "description": "Return budget status for a specific run.\n\nLoads the persisted cost tracker from ``.sdd/runtime/costs/{run_id}.json``\nand returns its ``BudgetStatus`` as JSON.", "operationId": "get_cost_budget_costs__run_id__get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "description": "No cost data for run" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/costs/export": { "get": { "summary": "Export Costs", "description": "Export cost data as CSV or JSON for finance analysis.\n\nArgs:\n request: FastAPI request.\n format: Export format ('csv' or 'json').\n\nReturns:\n File response with cost data in requested format.", "operationId": "export_costs_costs_export_get", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "default": "json", "title": "Format" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/costs/forecast": { "get": { "summary": "Forecast Costs", "description": "Forecast cost for next hour based on current burn rate.\n\nExtrapolates current spending rate to predict next hour's cost.\nUses recent task completion rate and average cost per task.", "operationId": "forecast_costs_costs_forecast_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/costs/compare": { "get": { "summary": "Compare Model Costs", "description": "Return live model cost comparison during execution.\n\nShows current costs by model with token usage statistics.", "operationId": "compare_model_costs_costs_compare_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/costs/cache-stats": { "get": { "summary": "Cache Stats", "description": "Return prompt cache hit rate statistics.\n\nShows cache hits/misses and savings by model.", "operationId": "cache_stats_costs_cache_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/costs/model-comparison": { "get": { "summary": "Model Cost Comparison", "description": "Return model cost comparison report.\n\nShows what the current run would have cost with different models.\nUseful for optimizing model routing decisions.", "operationId": "model_cost_comparison_costs_model_comparison_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/costs/token-efficiency": { "get": { "summary": "Token Efficiency", "description": "Compare token efficiency across models and tasks.\n\nRanks models by tokens per useful line of code.", "operationId": "token_efficiency_costs_token_efficiency_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/dashboard/file_locks": { "get": { "summary": "File Locks Endpoint", "description": "Return active file locks grouped by agent for the dashboard.\n\nReads the persisted lock state from ``.sdd/runtime/file_locks.json`` and\nreturns it in a dashboard-friendly format with both a flat list and an\nagent-grouped view.\n\nReturns:\n JSON with ``all_locks`` (flat list sorted by path), ``locks_by_agent``\n (dict keyed by agent_id with files list + task info + elapsed_s),\n ``count`` (total lock count), and ``ts`` (generation timestamp).", "operationId": "file_locks_endpoint_dashboard_file_locks_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/graph/impact": { "get": { "tags": [ "graph" ], "summary": "Graph Impact", "description": "Return downstream files impacted by changing the given file.", "operationId": "graph_impact_graph_impact_get", "parameters": [ { "name": "file", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "title": "File" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpactResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/observability/agents": { "get": { "summary": "Observability Agents", "description": "Return runtime heartbeat, stall-profile, and log-summary data per agent.", "operationId": "observability_agents_observability_agents_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Observability Agents Observability Agents Get" } } } } } } }, "/observability/effectiveness": { "get": { "summary": "Observability Effectiveness", "description": "Return recent effectiveness data, role trends, and best configs.", "operationId": "observability_effectiveness_observability_effectiveness_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Observability Effectiveness Observability Effectiveness Get" } } } } } } }, "/observability/recommendations": { "get": { "summary": "Observability Recommendations", "description": "Return the current recommendation set and delivery hit counts.", "operationId": "observability_recommendations_observability_recommendations_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Observability Recommendations Observability Recommendations Get" } } } } } } }, "/observability/budget": { "get": { "summary": "Observability Budget", "description": "Return completion-budget status per lineage.", "operationId": "observability_budget_observability_budget_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Observability Budget Observability Budget Get" } } } } } } }, "/observability/deps": { "get": { "summary": "Observability Deps", "description": "Return dependency-graph validation status for current tasks.", "operationId": "observability_deps_observability_deps_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Observability Deps Observability Deps Get" } } } } } } }, "/recap": { "get": { "summary": "Recap", "description": "Return post-run summary with diff stats, quality scores, and cost breakdown.\n\nReads completed tasks from the archive and computes:\n- Task completion statistics\n- Git diff statistics (files changed, additions, deletions)\n- Quality score distribution\n- Cost breakdown by model and role", "operationId": "recap_recap_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Recap Recap Get" } } } } } } }, "/observability/token-histogram": { "get": { "summary": "Token Histogram", "description": "Return histogram of token usage by task complexity.\n\nShows average tokens consumed for small, medium, large tasks.\nHelps understand token consumption patterns.", "operationId": "token_histogram_observability_token_histogram_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Token Histogram Observability Token Histogram Get" } } } } } } }, "/observability/queue-depth": { "get": { "summary": "Get Queue Depth", "description": "Return task queue depth over time.\n\nReturns last N records of queue depth snapshots.\n\nArgs:\n request: FastAPI request.\n limit: Maximum number of records to return (default 100).\n\nReturns:\n List of queue depth snapshots with timestamps.", "operationId": "get_queue_depth_observability_queue_depth_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Queue Depth Observability Queue Depth Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/observability/timeline": { "get": { "summary": "Get Timeline", "description": "Return task timing data for timeline visualization.\n\nReturns start and end times for all tasks tracked in metrics.", "operationId": "get_timeline_observability_timeline_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Timeline Observability Timeline Get" } } } } } } }, "/changelog": { "get": { "summary": "Get Changelog", "description": "Generate changelog from completed tasks.\n\nGroups completed tasks by type (Features, Fixes, etc.) and\nformats as markdown changelog.\n\nArgs:\n request: FastAPI request.\n days: Number of days to include (default 30).\n\nReturns:\n Dict with 'markdown' key containing changelog text.", "operationId": "get_changelog_changelog_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Changelog Changelog Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/observability/incidents": { "get": { "summary": "List Incidents", "description": "List all known incidents.\n\nReturns:\n Dict with 'incidents' list.", "operationId": "list_incidents_observability_incidents_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response List Incidents Observability Incidents Get" } } } } } } }, "/observability/incident-timeline/{incident_id}": { "get": { "summary": "Get Incident Timeline", "description": "Build a correlated incident timeline from logs, metrics, and traces.\n\nArgs:\n request: FastAPI request.\n incident_id: The incident ID to build a timeline for.\n window_before: Seconds before incident to include (default 600).\n window_after: Seconds after incident to include (default 300).\n\nReturns:\n Dict with incident metadata and sorted timeline events.", "operationId": "get_incident_timeline_observability_incident_timeline__incident_id__get", "parameters": [ { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Incident Id" } }, { "name": "window_before", "in": "query", "required": false, "schema": { "type": "integer", "default": 600, "title": "Window Before" } }, { "name": "window_after", "in": "query", "required": false, "schema": { "type": "integer", "default": 300, "title": "Window After" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Incident Timeline Observability Incident Timeline Incident Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/quality": { "get": { "summary": "Get Quality Metrics", "description": "Return aggregated internal quality metrics (last 7 days).\n\nReads from ``.sdd/metrics/`` JSONL files to compute:\n\n- ``per_model``: per-model success rate, avg tokens, and completion\n time distribution (p50/p90/p99).\n- ``overall``: aggregate across all models.\n- ``gate_stats``: per-gate pass/blocked/flagged counts (last 30 days).\n- ``guardrail_pass_rate``: fraction of gate checks that passed.\n- ``review_rejection_rate``: fraction of tasks that failed overall.\n\nReturns an empty structure when no metric data exists yet.", "operationId": "get_quality_metrics_quality_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/quality/budget-forecast": { "get": { "summary": "Get Budget Forecast", "description": "Return projected spend for the active planned backlog.", "operationId": "get_budget_forecast_quality_budget_forecast_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/quality/models": { "get": { "summary": "Get Quality By Model", "description": "Return per-model quality breakdown (last 30 days).\n\nExtended view of model performance for routing configuration and cost\nanalysis. Covers a longer window than the default ``/quality`` summary.", "operationId": "get_quality_by_model_quality_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/drain": { "get": { "summary": "Drain Status", "description": "Check drain status.", "operationId": "drain_status_drain_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } }, "post": { "summary": "Drain Start", "description": "Begin draining -- stop accepting new task claims.", "operationId": "drain_start_drain_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/drain/cancel": { "post": { "summary": "Drain Cancel", "description": "Cancel drain -- resume accepting claims.", "operationId": "drain_cancel_drain_cancel_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/identities": { "get": { "tags": [ "identities" ], "summary": "List Identities", "description": "List agent identities with optional status/role filters.", "operationId": "list_identities_identities_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "role", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/identities/{identity_id}": { "get": { "tags": [ "identities" ], "summary": "Get Identity", "description": "Get details for a single agent identity.", "operationId": "get_identity_identities__identity_id__get", "parameters": [ { "name": "identity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Identity Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Identity not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/identities/{identity_id}/revoke": { "post": { "tags": [ "identities" ], "summary": "Revoke Identity", "description": "Revoke an agent identity.", "operationId": "revoke_identity_identities__identity_id__revoke_post", "parameters": [ { "name": "identity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Identity Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Identity not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/identities/{identity_id}/audit": { "get": { "tags": [ "identities" ], "summary": "Identity Audit", "description": "Return the audit trail for an agent identity.", "operationId": "identity_audit_identities__identity_id__audit_get", "parameters": [ { "name": "identity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Identity Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/.well-known/acp.json": { "get": { "summary": "Acp Discovery", "description": "ACP discovery document — editors poll this to find ACP-compatible agents.", "operationId": "acp_discovery__well_known_acp_json_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ACPDiscoveryResponse" } } } } } } }, "/acp/v0/agents": { "get": { "summary": "List Acp Agents", "description": "List all ACP-advertised agents.", "operationId": "list_acp_agents_acp_v0_agents_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ACPAgentListEntry" }, "type": "array", "title": "Response List Acp Agents Acp V0 Agents Get" } } } } } } }, "/acp/v0/agents/{agent_id}": { "get": { "summary": "Get Acp Agent", "description": "Get detailed metadata for a specific ACP agent.", "operationId": "get_acp_agent_acp_v0_agents__agent_id__get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ACPAgentResponse" } } } }, "404": { "description": "ACP agent not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/acp/v0/runs": { "post": { "summary": "Create Acp Run", "description": "Create an ACP run — creates a Bernstein task and links it.\n\nEditors call this when the user submits a goal via the ACP sidebar.", "operationId": "create_acp_run_acp_v0_runs_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ACPRunCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ACPRunResponse" } } } }, "400": { "description": "Unknown ACP agent" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/acp/v0/runs/{run_id}": { "get": { "summary": "Get Acp Run", "description": "Get ACP run status, syncing from the underlying Bernstein task.", "operationId": "get_acp_run_acp_v0_runs__run_id__get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ACPRunResponse" } } } }, "404": { "description": "ACP run not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "summary": "Cancel Acp Run", "description": "Cancel an ACP run and its underlying Bernstein task.", "operationId": "cancel_acp_run_acp_v0_runs__run_id__delete", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ACPRunResponse" } } } }, "404": { "description": "ACP run not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/approvals": { "get": { "tags": [ "approvals" ], "summary": "List Approvals", "description": "List all pending approval requests.", "operationId": "list_approvals_approvals_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApprovalsResponse" } } } } } } }, "/approvals/{task_id}/approve": { "post": { "tags": [ "approvals" ], "summary": "Approve Task", "description": "Approve a pending approval request.\n\nWrites a .approved decision file so the orchestrator poll loop unblocks.\nThe pending file is then removed.\n\nArgs:\n task_id: Task ID to approve.\n body: Optional reason metadata.\n\nReturns:\n Success message.", "operationId": "approve_task_approvals__task_id__approve_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecisionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Approve Task Approvals Task Id Approve Post" } } } }, "400": { "description": "Invalid task_id format" }, "404": { "description": "No pending approval for task" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/approvals/{task_id}/reject": { "post": { "tags": [ "approvals" ], "summary": "Reject Task", "description": "Reject a pending approval request.\n\nWrites a .rejected decision file so the orchestrator poll loop unblocks.\nThe pending file is then removed.\n\nArgs:\n task_id: Task ID to reject.\n body: Optional reason metadata.\n\nReturns:\n Success message.", "operationId": "reject_task_approvals__task_id__reject_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecisionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Reject Task Approvals Task Id Reject Post" } } } }, "400": { "description": "Invalid task_id format" }, "404": { "description": "No pending approval for task" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/plans": { "get": { "tags": [ "plans" ], "summary": "List Plans", "description": "List all plans, optionally filtered by status.\n\nQuery params:\n status: Filter by plan status (pending, approved, rejected, expired).", "operationId": "list_plans_plans_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response List Plans Plans Get" } } } }, "400": { "description": "Invalid status filter" }, "503": { "description": "Plan store not initialized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/plans/{plan_id}": { "get": { "tags": [ "plans" ], "summary": "Get Plan", "description": "Get a single plan by ID.", "operationId": "get_plan_plans__plan_id__get", "parameters": [ { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Plan Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Plan Plans Plan Id Get" } } } }, "404": { "description": "Plan not found" }, "503": { "description": "Plan store not initialized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/plans/{plan_id}/approve": { "post": { "tags": [ "plans" ], "summary": "Approve Plan", "description": "Approve a plan: promotes all its PLANNED tasks to OPEN.\n\nThis is the key operation: once approved, the orchestrator will\npick up the tasks and start spawning agents.", "operationId": "approve_plan_plans__plan_id__approve_post", "parameters": [ { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Plan Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PlanDecisionRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Approve Plan Plans Plan Id Approve Post" } } } }, "404": { "description": "Plan not found" }, "409": { "description": "Plan already decided" }, "503": { "description": "Plan store not initialized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/plans/{plan_id}/reject": { "post": { "tags": [ "plans" ], "summary": "Reject Plan", "description": "Reject a plan: cancels all its PLANNED tasks.\n\nRejected tasks are moved to CANCELLED status so they never execute.", "operationId": "reject_plan_plans__plan_id__reject_post", "parameters": [ { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Plan Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PlanDecisionRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Reject Plan Plans Plan Id Reject Post" } } } }, "404": { "description": "Plan not found" }, "409": { "description": "Plan already decided" }, "503": { "description": "Plan store not initialized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/gateway/metrics": { "get": { "summary": "Gateway Metrics", "description": "Return per-tool MCP call metrics from the active gateway session.\n\nReturns an empty ``metrics`` dict when no gateway is running.\nClients can use ``active`` to distinguish the two cases.", "operationId": "gateway_metrics_gateway_metrics_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/slo": { "get": { "summary": "Get Slo Status", "description": "Return current SLO dashboard data.", "operationId": "get_slo_status_slo_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/slo/budget": { "get": { "summary": "Get Error Budget", "description": "Return error budget details in focused format.", "operationId": "get_error_budget_slo_budget_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/slo/reset": { "post": { "summary": "Reset Slo State", "description": "Reset SLO tracker to initial state (no persisted data cleared).", "operationId": "reset_slo_state_slo_reset_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/hooks/{session_id}": { "post": { "summary": "Receive Hook", "description": "Receive a hook event from Claude Code.\n\nClaude Code sends structured JSON with at minimum a ``hook_event_name``\nfield. The event is parsed, persisted to a JSONL sidecar, and triggers\nside effects (heartbeat touch, completion markers, etc.).\n\nArgs:\n session_id: Agent session identifier from the URL path.\n request: The incoming FastAPI request.\n\nReturns:\n JSON response with status and action taken.", "operationId": "receive_hook_hooks__session_id__post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/export/tasks": { "get": { "summary": "Export Tasks", "description": "Export all tasks as CSV or JSON.\n\nQuery params:\n format: ``csv`` or ``json`` (default ``json``).", "operationId": "export_tasks_export_tasks_get", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "default": "json", "title": "Format" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/export/agents": { "get": { "summary": "Export Agents", "description": "Export agent snapshots as CSV or JSON.\n\nQuery params:\n format: ``csv`` or ``json`` (default ``json``).", "operationId": "export_agents_export_agents_get", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "default": "json", "title": "Format" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/grafana/dashboard": { "get": { "summary": "Grafana Dashboard Endpoint", "description": "Generate and return the Grafana dashboard JSON.\n\nQuery params:\n datasource: Prometheus datasource name (default ``Prometheus``).", "operationId": "grafana_dashboard_endpoint_grafana_dashboard_get", "parameters": [ { "name": "datasource", "in": "query", "required": false, "schema": { "type": "string", "default": "Prometheus", "title": "Datasource" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/tasks/{task_id}": { "get": { "summary": "Task Detail", "description": "Return detailed task view including log tail and progress.\n\nArgs:\n task_id: Task identifier.", "operationId": "task_detail_dashboard_tasks__task_id__get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/tasks/{task_id}/logs/stream": { "get": { "summary": "Task Log Stream", "description": "Stream agent logs for a task via Server-Sent Events.\n\nThe stream sends new log content as ``log`` events and closes\nafter the task completes or ``_MAX_IDLE_TICKS`` seconds of no new data.", "operationId": "task_log_stream_dashboard_tasks__task_id__logs_stream_get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/health/deps": { "get": { "summary": "Health Deps", "description": "Return health status with dependency checks.\n\nChecks: server, store, adapters, sse_bus.\nOverall status is ``healthy`` if all dependencies are ok,\n``degraded`` if any are degraded, ``unhealthy`` if any are down.", "operationId": "health_deps_health_deps_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthDepsResponse" } } } } } } }, "/api/v1/tasks/search": { "get": { "summary": "Search Tasks", "description": "Search tasks with pagination, sorting, and filtering.\n\nQuery params:\n page: Page number (1-based, default 1).\n per_page: Items per page (1-100, default 20).\n sort: Sort field (created_at, priority, title, role, status).\n order: Sort order (asc, desc; default desc).\n status: Filter by task status.\n role: Filter by task role.\n assigned_agent: Filter by assigned agent.", "operationId": "search_tasks_api_v1_tasks_search_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "title": "Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Per Page" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at", "title": "Sort" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Order" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "role", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" } }, { "name": "assigned_agent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks": { "post": { "summary": "Create Task", "description": "Create a new task.", "operationId": "create_task_api_v1_tasks_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "description": "Blocked by pre-create hook" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "List Tasks", "description": "List tasks, optionally filtered by status, cell_id, and/or claim owner.\n\nWhen ``limit`` or ``offset`` query params are provided the response is a\npaginated envelope (``{tasks, total, limit, offset}``). Without them,\nthe legacy flat list is returned for backward compatibility.\n\nArgs:\n request: FastAPI request.\n status: If provided, only tasks with this status are returned.\n cell_id: If provided, only tasks in this cell are returned.\n tenant: Tenant scope override.\n claimed_by_session: If provided, only tasks claimed by this parent\n orchestrator session are returned.\n limit: Maximum number of tasks to return (max 500). Triggers\n paginated response when present.\n offset: Number of tasks to skip. Triggers paginated response\n when present.\n\nReturns:\n Paginated response **or** plain list of TaskResponse dicts.", "operationId": "list_tasks_api_v1_tasks_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "cell_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cell Id" } }, { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } }, { "name": "claimed_by_session", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claimed By Session" } }, { "name": "parent_session_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Session Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PaginatedTasksResponse" }, { "type": "array", "items": { "$ref": "#/components/schemas/TaskResponse" } } ], "title": "Response List Tasks Api V1 Tasks Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/batch": { "post": { "summary": "Create Tasks Batch", "description": "Create multiple tasks atomically with title dedup.", "operationId": "create_tasks_batch_api_v1_tasks_batch_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateResponse" } } } }, "503": { "description": "Server is draining" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/self-create": { "post": { "summary": "Self Create Subtask", "description": "Create a subtask linked to a parent task.\n\nAgents call this to decompose work during execution. The parent\ntask is automatically transitioned to ``WAITING_FOR_SUBTASKS`` on\nthe first subtask creation (if it is not already in that state).", "operationId": "self_create_subtask_api_v1_tasks_self_create_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSelfCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Parent task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/next/{role}": { "get": { "summary": "Next Task", "description": "Claim the next available task for *role*.\n\nPass ``claimed_by_session`` as a query param to record which parent\norchestrator session owns the claim.\n\nPass ``parent_session_id`` to restrict claiming to tasks that were\ncreated under that coordinator session. Workers belonging to a\ncoordinator should always pass their coordinator's session ID here\nto avoid stealing tasks from other namespaces.", "operationId": "next_task_api_v1_tasks_next__role__get", "parameters": [ { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "title": "Role" } }, { "name": "claimed_by_session", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claimed By Session" } }, { "name": "parent_session_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "No open tasks for role" }, "503": { "description": "Server is draining" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/claim-batch": { "post": { "summary": "Claim Batch", "description": "Atomically claim multiple tasks by ID for an agent.", "operationId": "claim_batch_api_v1_tasks_claim_batch_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchClaimRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchClaimResponse" } } } }, "503": { "description": "Server is draining" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/claim": { "post": { "summary": "Claim Task", "description": "Claim a specific task by ID.\n\nPass ``expected_version`` as a query param for optimistic locking\n(CAS). If the task's version doesn't match, returns 409 Conflict.\n\nPass ``claimed_by_session`` to record which parent orchestrator\nsession owns this claim.", "operationId": "claim_task_api_v1_tasks__task_id__claim_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "expected_version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expected Version" } }, { "name": "claimed_by_session", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claimed By Session" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Version conflict or invalid state" }, "503": { "description": "Server is draining" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/complete": { "post": { "summary": "Complete Task", "description": "Mark a task as done with a result summary.", "operationId": "complete_task_api_v1_tasks__task_id__complete_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCompleteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/wait-for-subtasks": { "post": { "summary": "Wait For Subtasks", "description": "Mark a parent task as waiting until its generated subtasks complete.", "operationId": "wait_for_subtasks_api_v1_tasks__task_id__wait_for_subtasks_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskWaitForSubtasksRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/fail": { "post": { "summary": "Fail Task", "description": "Mark a task as failed.", "operationId": "fail_task_api_v1_tasks__task_id__fail_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskFailRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/close": { "post": { "summary": "Close Task", "description": "Mark a verified task as closed (terminal success state).", "operationId": "close_task_api_v1_tasks__task_id__close_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/cancel": { "post": { "summary": "Cancel Task", "description": "Cancel a task that has not yet finished.", "operationId": "cancel_task_api_v1_tasks__task_id__cancel_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCancelRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/block": { "post": { "summary": "Block Task", "description": "Mark a task as blocked -- requires human intervention to unblock.", "operationId": "block_task_api_v1_tasks__task_id__block_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskBlockRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Invalid state transition" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/progress": { "post": { "summary": "Progress Task", "description": "Append an intermediate progress update to a task.\n\nAlso stores a progress snapshot for stall detection when snapshot\nfields (files_changed, tests_passing, errors) are provided.", "operationId": "progress_task_api_v1_tasks__task_id__progress_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskProgressRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/snapshots": { "get": { "summary": "Get Task Snapshots", "description": "Return stored progress snapshots for a task (oldest-first, up to 10).", "operationId": "get_task_snapshots_api_v1_tasks__task_id__snapshots_get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SnapshotEntry" }, "title": "Response Get Task Snapshots Api V1 Tasks Task Id Snapshots Get" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/counts": { "get": { "summary": "Task Counts", "description": "Return task counts per status without serialising task bodies.\n\nThis is the lightweight alternative to GET /tasks for orchestrator\ntick summaries and dashboard polling.", "operationId": "task_counts_api_v1_tasks_counts_get", "parameters": [ { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCountsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/archive": { "get": { "summary": "Get Archive", "description": "Return the last N archived (done/failed) task records.", "operationId": "get_archive_api_v1_tasks_archive_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArchiveRecord" }, "title": "Response Get Archive Api V1 Tasks Archive Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/graph": { "get": { "summary": "Get Task Graph", "description": "Return the task dependency graph as JSON (nodes + edges + critical path).\n\nBuilds a DAG from all current tasks and returns:\n- ``nodes``: list of {id, role, status, estimated_minutes, title}\n- ``edges``: list of {from, to, type, semantic_type}\n- ``critical_path``: ordered list of task IDs on the longest chain\n- ``critical_path_minutes``: total estimated minutes on the critical path\n- ``parallel_width``: max tasks that can run concurrently\n- ``bottlenecks``: task IDs that block the most downstream work", "operationId": "get_task_graph_api_v1_tasks_graph_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/tasks/{task_id}": { "get": { "summary": "Get Task", "description": "Get a single task by ID.", "operationId": "get_task_api_v1_tasks__task_id__get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "summary": "Patch Task", "description": "Update mutable task fields (role, priority, model) — manager corrections.\n\nUsed by the manager agent or dashboard to correct mis-assigned tasks,\nadjust priority, or change model without interrupting the orchestrator.", "operationId": "patch_task_api_v1_tasks__task_id__patch", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskPatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/gates": { "get": { "summary": "Get Task Gates", "description": "Return the persisted quality-gate report for a task.", "operationId": "get_task_gates_api_v1_tasks__task_id__gates_get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Task or gate report not found" }, "500": { "description": "Gate report unreadable" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/prioritize": { "post": { "summary": "Prioritize Task", "description": "Bump a task to priority 0 so the orchestrator picks it up next.", "operationId": "prioritize_task_api_v1_tasks__task_id__prioritize_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/force-claim": { "post": { "summary": "Force Claim Task", "description": "Force a task back to open with priority 0 for immediate pickup.\n\nResets claimed/in_progress tasks back to open so the orchestrator's\nnext tick will spawn a fresh agent for them. Terminal tasks\n(done/failed/cancelled) are rejected with 409.", "operationId": "force_claim_task_api_v1_tasks__task_id__force_claim_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Task not found" }, "409": { "description": "Cannot force-claim terminal task" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/heartbeat": { "post": { "summary": "Agent Heartbeat", "description": "Register an agent heartbeat.", "operationId": "agent_heartbeat_api_v1_agents__agent_id__heartbeat_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{session_id}/logs": { "get": { "summary": "Agent Logs", "description": "Return the log content for a running or finished agent session.\n\nArgs:\n session_id: Agent session identifier (e.g. ``backend-abc12345``).\n tail_bytes: When > 0, only the last *tail_bytes* of the file are\n returned (partial leading line is stripped). 0 means full file.\n\nReturns:\n JSON with ``session_id``, ``content`` string, and ``size`` in bytes.\n\nRaises:\n HTTPException: 404 when no log file exists for the session.", "operationId": "agent_logs_api_v1_agents__session_id__logs_get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "tail_bytes", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Tail Bytes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "description": "No log for session" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{session_id}/kill": { "post": { "summary": "Agent Kill", "description": "Request termination of an agent by writing a ``.kill`` signal file.\n\nThe orchestrator polls for these files on each tick and calls\n``spawner.kill(session)`` for the matching session.\n\nArgs:\n session_id: Agent session to terminate.\n\nReturns:\n JSON with ``session_id`` and ``kill_requested: true``.", "operationId": "agent_kill_api_v1_agents__session_id__kill_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{session_id}/stream": { "get": { "summary": "Agent Stream", "description": "Server-Sent Events stream of agent output for the given session.\n\nReplays all existing log content first, then tails the file for new\nlines. Closes automatically after ``_MAX_IDLE_TICKS`` consecutive\npolls with no new data (or no log file).\n\nSSE event format::\n\n data: {\"type\": \"connected\", \"session_id\": \"\"}\n\n data: {\"line\": \"\"}\n\nArgs:\n session_id: Agent session to stream output for.\n\nReturns:\n StreamingResponse with ``text/event-stream`` media type.", "operationId": "agent_stream_api_v1_agents__session_id__stream_get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/bulletin": { "post": { "summary": "Post Bulletin", "description": "Append a message to the bulletin board.", "operationId": "post_bulletin_api_v1_bulletin_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulletinPostRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulletinMessageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "Get Bulletin", "description": "Get bulletin messages since a given timestamp.", "operationId": "get_bulletin_api_v1_bulletin_get", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "number", "default": 0.0, "title": "Since" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BulletinMessageResponse" }, "title": "Response Get Bulletin Api V1 Bulletin Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/.well-known/agent.json": { "get": { "summary": "Agent Card", "description": "Publish the Bernstein orchestrator Agent Card (A2A spec).", "operationId": "agent_card_api_v1__well_known_agent_json_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AAgentCardResponse" } } } } } } }, "/api/v1/a2a/agents": { "get": { "summary": "List A2A Agents", "description": "Return Bernstein's A2A agent card via the task API namespace.", "operationId": "list_a2a_agents_api_v1_a2a_agents_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AAgentCardResponse" } } } } } } }, "/api/v1/a2a/message": { "post": { "summary": "A2A Message", "description": "Receive an inbound A2A message and inject it into the target task context.", "operationId": "a2a_message_api_v1_a2a_message_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AMessageRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AMessageResponse" } } } }, "404": { "description": "Task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/a2a/tasks/send": { "post": { "summary": "A2A Send Task", "description": "Receive a task from an external A2A agent.\n\nCreates both an A2A task record and a corresponding Bernstein task,\nlinking them together for lifecycle synchronisation.", "operationId": "a2a_send_task_api_v1_a2a_tasks_send_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ATaskSendRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ATaskResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/a2a/tasks/{a2a_task_id}": { "get": { "summary": "A2A Get Task", "description": "Get an A2A task by ID, syncing status from the Bernstein task.", "operationId": "a2a_get_task_api_v1_a2a_tasks__a2a_task_id__get", "parameters": [ { "name": "a2a_task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "A2A Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ATaskResponse" } } } }, "404": { "description": "A2A task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/a2a/tasks/{a2a_task_id}/artifacts": { "post": { "summary": "A2A Add Artifact", "description": "Attach an artifact to an A2A task.", "operationId": "a2a_add_artifact_api_v1_a2a_tasks__a2a_task_id__artifacts_post", "parameters": [ { "name": "a2a_task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "A2A Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AArtifactRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AArtifactResponse" } } } }, "404": { "description": "A2A task not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/cluster/nodes": { "post": { "summary": "Register Node", "description": "Register a new node in the cluster.", "operationId": "register_node_api_v1_cluster_nodes_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeRegisterRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "List Nodes", "description": "List all cluster nodes, optionally filtered by status.", "operationId": "list_nodes_api_v1_cluster_nodes_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NodeResponse" }, "title": "Response List Nodes Api V1 Cluster Nodes Get" } } } }, "400": { "description": "Invalid node status" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/cluster/nodes/{node_id}/heartbeat": { "post": { "summary": "Node Heartbeat", "description": "Record a heartbeat from a cluster node.", "operationId": "node_heartbeat_api_v1_cluster_nodes__node_id__heartbeat_post", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeHeartbeatRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeResponse" } } } }, "404": { "description": "Node not registered" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/cluster/nodes/{node_id}": { "delete": { "summary": "Unregister Node", "description": "Remove a node from the cluster.", "operationId": "unregister_node_api_v1_cluster_nodes__node_id__delete", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "responses": { "204": { "description": "Successful Response" }, "404": { "description": "Node not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/cluster/nodes/{node_id}/cordon": { "post": { "summary": "Cordon Node", "description": "Cordon a node -- exclude from scheduling.", "operationId": "cordon_node_api_v1_cluster_nodes__node_id__cordon_post", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Cordon Node Api V1 Cluster Nodes Node Id Cordon Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/cluster/nodes/{node_id}/uncordon": { "post": { "summary": "Uncordon Node", "description": "Uncordon a node -- resume accepting tasks.", "operationId": "uncordon_node_api_v1_cluster_nodes__node_id__uncordon_post", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Uncordon Node Api V1 Cluster Nodes Node Id Uncordon Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/cluster/nodes/{node_id}/drain": { "post": { "summary": "Drain Node", "description": "Start draining a node -- cordon + signal agents to finish.", "operationId": "drain_node_api_v1_cluster_nodes__node_id__drain_post", "parameters": [ { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Drain Node Api V1 Cluster Nodes Node Id Drain Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/cluster/status": { "get": { "summary": "Cluster Status", "description": "Get cluster status summary.", "operationId": "cluster_status_api_v1_cluster_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterStatusResponse" } } } } } } }, "/api/v1/cluster/steal": { "post": { "summary": "Steal Tasks", "description": "Evaluate task stealing policy and reassign claimed tasks between nodes.\n\nWorkers report their queue depths; the server runs the steal policy and\nreturns a list of task reassignments. Stolen tasks are reset to ``open``\nso the receiver node can claim them.", "operationId": "steal_tasks_api_v1_cluster_steal_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStealRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStealResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/status": { "get": { "summary": "Status Dashboard", "description": "Dashboard summary of task counts.", "operationId": "status_dashboard_api_v1_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/status/duration-predictions": { "get": { "summary": "Duration Predictions", "description": "Return ML-predicted duration estimates for all open/claimed tasks.\n\nUses the local GradientBoosting duration predictor. Falls back to the\nstatic cold-start table when fewer than 50 completions are available.\n\nResponse shape::\n\n {\n \"predictor\": {\n \"trained\": true,\n \"training_samples\": 142,\n \"cold_start\": false\n },\n \"tasks\": [\n {\n \"task_id\": \"abc123\",\n \"title\": \"Refactor auth module\",\n \"role\": \"backend\",\n \"p50_seconds\": 720.0,\n \"p90_seconds\": 1440.0,\n \"confidence\": 0.62,\n \"is_cold_start\": false,\n \"eta_p50\": \"12m 0s\",\n \"eta_p90\": \"24m 0s\"\n }\n ]\n }", "operationId": "duration_predictions_api_v1_status_duration_predictions_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/routing/bandit": { "get": { "summary": "Bandit Routing Stats", "description": "Return contextual bandit routing statistics.\n\nReads persisted state from ``.sdd/routing/``. Returns an empty dict\nwhen bandit routing has not been activated (``--routing bandit`` not passed).", "operationId": "bandit_routing_stats_api_v1_routing_bandit_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/health": { "get": { "summary": "Health Check", "description": "Liveness check with component-level status.", "operationId": "health_check_api_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/v1/health/ready": { "get": { "summary": "Ready Check", "description": "Readiness check for load balancers.", "operationId": "ready_check_api_v1_health_ready_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/ready": { "get": { "summary": "Ready Alias", "description": "Alias for /health/ready.", "operationId": "ready_alias_api_v1_ready_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/health/live": { "get": { "summary": "Live Check", "description": "Liveness check for process monitoring.", "operationId": "live_check_api_v1_health_live_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/alive": { "get": { "summary": "Live Alias", "description": "Alias for /health/live.", "operationId": "live_alias_api_v1_alive_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/config": { "post": { "summary": "Update Config", "description": "Update mutable config fields at runtime.\n\nAccepts JSON body with ``{\"max_agents\": N}``. Writes the change to\n``bernstein.yaml`` so the orchestrator's hot-reload picks it up on\nthe next tick (~30s). Returns the new effective value.", "operationId": "update_config_api_v1_config_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/shutdown": { "post": { "summary": "Shutdown Server", "description": "Initiate graceful server shutdown.\n\nAccepts an optional JSON body ``{\"reason\": \"...\"}``. Schedules a\nSIGTERM to the current process shortly after the response is sent so\nthat the Uvicorn server exits cleanly.", "operationId": "shutdown_server_api_v1_shutdown_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/cache-stats": { "get": { "summary": "Cache Stats", "description": "Return prompt caching statistics from the manifest.\n\nReads `.sdd/caching/manifest.jsonl` and returns aggregated counts,\nestimated token savings, and estimated USD savings based on the\nAnthropic cached-input discount (90% off standard input price).\n\nReturns 200 with empty statistics if no cache manifest exists yet.", "operationId": "cache_stats_api_v1_cache_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/metrics": { "get": { "summary": "Metrics Endpoint", "description": "Prometheus metrics scrape endpoint.\n\nUpdates all gauges from the current task store state, then\nreturns the full metric exposition in Prometheus text format.", "operationId": "metrics_endpoint_api_v1_metrics_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/dashboard": { "get": { "summary": "Dashboard Page", "description": "Serve the single-page web dashboard.", "operationId": "dashboard_page_api_v1_dashboard_get", "responses": { "200": { "description": "Successful Response", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/api/v1/dashboard/data": { "get": { "summary": "Dashboard Data", "description": "Return all mission control dashboard data as JSON.\n\nIncludes stats, tasks with timeline data, agent details with costs,\nfile ownership map, cost history, and alerts.", "operationId": "dashboard_data_api_v1_dashboard_data_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/memory/audit": { "get": { "summary": "Memory Audit", "description": "Audit the lesson memory provenance chain (OWASP ASI06 2026).\n\nReturns chain integrity status and a per-entry provenance trail.\nDetects tampering, insertion, deletion, and reordering attacks.", "operationId": "memory_audit_api_v1_memory_audit_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/broadcast": { "post": { "summary": "Broadcast Command", "description": "Send a message to all running agents via fastest available channel.\n\nUses stdin pipe where available (sub-second delivery), falls back\nto file-based COMMAND signal for agents without pipe support.\n\nExpects JSON body: ``{\"message\": \"some instruction\"}``.", "operationId": "broadcast_command_api_v1_broadcast_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/events": { "get": { "summary": "Sse Events", "description": "Server-Sent Events stream for real-time dashboard updates.\n\nIncludes disconnect detection via heartbeat pings and connection\ntimeout handling to prevent leaked subscriber queues.", "operationId": "sse_events_api_v1_events_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/badge.json": { "get": { "summary": "Get Badge", "description": "Return dynamic badge data for GitHub shields.io integration.\n\nShows tasks completed, total cost, and quality score.\nUsage: https://img.shields.io/endpoint?url=/badge.json", "operationId": "get_badge_api_v1_badge_json_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/events/cost": { "get": { "summary": "Cost Events", "description": "SSE endpoint for real-time cost updates.\n\nListens to the global SSE bus for ``bulletin`` events that match\nthe ``live_cost_update`` status pattern and forwards them to clients.\nAlso provides periodic heartbeats.", "operationId": "cost_events_api_v1_events_cost_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/costs": { "get": { "summary": "Get Costs", "description": "Aggregate cost data across all runs.\n\nScans every persisted cost file in ``.sdd/runtime/costs/``, aggregates\nper-agent and per-model totals, and computes cost attainment as\n``(total_spent / total_budget) * 100``. Budget of zero is treated as\nunlimited — attainment is reported as 0.0 in that case.", "operationId": "get_costs_api_v1_costs_get", "parameters": [ { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Tenant access denied" }, "404": { "description": "Tenant not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/costs/live": { "get": { "summary": "Get Cost Live", "description": "Return live cost breakdown for the most recent run.\n\nFinds the most recently modified cost file in ``.sdd/runtime/costs/``,\nloads it, and returns budget status plus per-agent and per-model\ncost breakdowns.", "operationId": "get_cost_live_api_v1_costs_live_get", "parameters": [ { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Tenant access denied" }, "404": { "description": "Tenant not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/costs/current": { "get": { "summary": "Get Cost Current", "description": "Return real-time cost snapshot for the active run.\n\nUpdated after each agent completion. Designed for TUI sidebar polling\nand lightweight dashboard widgets. Returns per-model input/output/cache\ntoken breakdown alongside spend and budget status.", "operationId": "get_cost_current_api_v1_costs_current_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/costs/alerts": { "get": { "summary": "Get Cost Alerts", "description": "Return active budget alerts and 30d/90d cost trends.\n\nReads the live cost data for the most recent run, checks whether spend\nhas reached the 80% or 95% alert threshold, and returns trend data\ncomputed from ``.sdd/metrics/cost_history.jsonl``.", "operationId": "get_cost_alerts_api_v1_costs_alerts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/costs/history": { "get": { "summary": "Get Cost History", "description": "Return daily cost history with burn rate for chart visualization.\n\nLoads daily snapshots from ``.sdd/metrics/cost_history.jsonl`` and computes\na burn rate from the most recent 7 days. Burn rate is expressed both as\nUSD/day (7-day trailing average) and USD/hour.", "operationId": "get_cost_history_api_v1_costs_history_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/costs/{run_id}": { "get": { "summary": "Get Cost Budget", "description": "Return budget status for a specific run.\n\nLoads the persisted cost tracker from ``.sdd/runtime/costs/{run_id}.json``\nand returns its ``BudgetStatus`` as JSON.", "operationId": "get_cost_budget_api_v1_costs__run_id__get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "description": "No cost data for run" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/costs/export": { "get": { "summary": "Export Costs", "description": "Export cost data as CSV or JSON for finance analysis.\n\nArgs:\n request: FastAPI request.\n format: Export format ('csv' or 'json').\n\nReturns:\n File response with cost data in requested format.", "operationId": "export_costs_api_v1_costs_export_get", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "default": "json", "title": "Format" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/costs/forecast": { "get": { "summary": "Forecast Costs", "description": "Forecast cost for next hour based on current burn rate.\n\nExtrapolates current spending rate to predict next hour's cost.\nUses recent task completion rate and average cost per task.", "operationId": "forecast_costs_api_v1_costs_forecast_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/costs/compare": { "get": { "summary": "Compare Model Costs", "description": "Return live model cost comparison during execution.\n\nShows current costs by model with token usage statistics.", "operationId": "compare_model_costs_api_v1_costs_compare_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/costs/cache-stats": { "get": { "summary": "Cache Stats", "description": "Return prompt cache hit rate statistics.\n\nShows cache hits/misses and savings by model.", "operationId": "cache_stats_api_v1_costs_cache_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/costs/model-comparison": { "get": { "summary": "Model Cost Comparison", "description": "Return model cost comparison report.\n\nShows what the current run would have cost with different models.\nUseful for optimizing model routing decisions.", "operationId": "model_cost_comparison_api_v1_costs_model_comparison_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/costs/token-efficiency": { "get": { "summary": "Token Efficiency", "description": "Compare token efficiency across models and tasks.\n\nRanks models by tokens per useful line of code.", "operationId": "token_efficiency_api_v1_costs_token_efficiency_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/export/tasks": { "get": { "summary": "Export Tasks", "description": "Export all tasks as CSV or JSON.\n\nQuery params:\n format: ``csv`` or ``json`` (default ``json``).", "operationId": "export_tasks_api_v1_export_tasks_get", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "default": "json", "title": "Format" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/export/agents": { "get": { "summary": "Export Agents", "description": "Export agent snapshots as CSV or JSON.\n\nQuery params:\n format: ``csv`` or ``json`` (default ``json``).", "operationId": "export_agents_api_v1_export_agents_get", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "default": "json", "title": "Format" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/grafana/dashboard": { "get": { "summary": "Grafana Dashboard Endpoint", "description": "Generate and return the Grafana dashboard JSON.\n\nQuery params:\n datasource: Prometheus datasource name (default ``Prometheus``).", "operationId": "grafana_dashboard_endpoint_api_v1_grafana_dashboard_get", "parameters": [ { "name": "datasource", "in": "query", "required": false, "schema": { "type": "string", "default": "Prometheus", "title": "Datasource" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/health/deps": { "get": { "summary": "Health Deps", "description": "Return health status with dependency checks.\n\nChecks: server, store, adapters, sse_bus.\nOverall status is ``healthy`` if all dependencies are ok,\n``degraded`` if any are degraded, ``unhealthy`` if any are down.", "operationId": "health_deps_api_v1_health_deps_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthDepsResponse" } } } } } } } }, "components": { "schemas": { "A2AAgentCardResponse": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "capabilities": { "items": { "type": "string" }, "type": "array", "title": "Capabilities" }, "protocol_version": { "type": "string", "title": "Protocol Version" }, "endpoint": { "type": "string", "title": "Endpoint" }, "provider": { "type": "string", "title": "Provider" } }, "type": "object", "required": [ "name", "description", "capabilities", "protocol_version", "endpoint", "provider" ], "title": "A2AAgentCardResponse", "description": "Agent Card response for /.well-known/agent.json." }, "A2AArtifactRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "data": { "type": "string", "title": "Data", "default": "" }, "content_type": { "type": "string", "title": "Content Type", "default": "text/plain" } }, "type": "object", "required": [ "name" ], "title": "A2AArtifactRequest", "description": "Body for POST /a2a/tasks/{id}/artifacts — attach an artifact." }, "A2AArtifactResponse": { "properties": { "name": { "type": "string", "title": "Name" }, "content_type": { "type": "string", "title": "Content Type" }, "data": { "type": "string", "title": "Data" }, "created_at": { "type": "number", "title": "Created At" } }, "type": "object", "required": [ "name", "content_type", "data", "created_at" ], "title": "A2AArtifactResponse", "description": "Single artifact in responses." }, "A2AMessageRequest": { "properties": { "sender": { "type": "string", "title": "Sender" }, "recipient": { "type": "string", "title": "Recipient" }, "content": { "type": "string", "title": "Content" }, "task_id": { "type": "string", "title": "Task Id" } }, "type": "object", "required": [ "sender", "recipient", "content", "task_id" ], "title": "A2AMessageRequest", "description": "Body for POST /a2a/message." }, "A2AMessageResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "sender": { "type": "string", "title": "Sender" }, "recipient": { "type": "string", "title": "Recipient" }, "content": { "type": "string", "title": "Content" }, "task_id": { "type": "string", "title": "Task Id" }, "direction": { "type": "string", "title": "Direction" }, "delivered": { "type": "boolean", "title": "Delivered" }, "external_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Endpoint" }, "created_at": { "type": "number", "title": "Created At" } }, "type": "object", "required": [ "id", "sender", "recipient", "content", "task_id", "direction", "delivered", "external_endpoint", "created_at" ], "title": "A2AMessageResponse", "description": "Serialized A2A message returned by Bernstein endpoints." }, "A2ATaskResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "bernstein_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bernstein Task Id" }, "sender": { "type": "string", "title": "Sender" }, "message": { "type": "string", "title": "Message" }, "status": { "type": "string", "title": "Status" }, "artifacts": { "items": { "$ref": "#/components/schemas/A2AArtifactResponse" }, "type": "array", "title": "Artifacts" }, "created_at": { "type": "number", "title": "Created At" }, "updated_at": { "type": "number", "title": "Updated At" } }, "type": "object", "required": [ "id", "bernstein_task_id", "sender", "message", "status", "artifacts", "created_at", "updated_at" ], "title": "A2ATaskResponse", "description": "Serialised A2A task in responses." }, "A2ATaskSendRequest": { "properties": { "sender": { "type": "string", "title": "Sender" }, "message": { "type": "string", "title": "Message" }, "role": { "type": "string", "title": "Role", "default": "backend" } }, "type": "object", "required": [ "sender", "message" ], "title": "A2ATaskSendRequest", "description": "Body for POST /a2a/tasks/send — receive a task from an external A2A agent." }, "ACPAgentCapabilityResponse": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "input_schema": { "additionalProperties": true, "type": "object", "title": "Input Schema" } }, "type": "object", "required": [ "name", "description" ], "title": "ACPAgentCapabilityResponse", "description": "Single ACP capability entry." }, "ACPAgentListEntry": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "endpoint": { "type": "string", "title": "Endpoint" } }, "type": "object", "required": [ "name", "description", "endpoint" ], "title": "ACPAgentListEntry", "description": "Entry in the agents list." }, "ACPAgentResponse": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "protocol_version": { "type": "string", "title": "Protocol Version" }, "capabilities": { "items": { "$ref": "#/components/schemas/ACPAgentCapabilityResponse" }, "type": "array", "title": "Capabilities" }, "endpoint": { "type": "string", "title": "Endpoint" }, "provider": { "type": "string", "title": "Provider" } }, "type": "object", "required": [ "name", "description", "protocol_version", "capabilities", "endpoint", "provider" ], "title": "ACPAgentResponse", "description": "ACP agent metadata." }, "ACPDiscoveryResponse": { "properties": { "protocol": { "type": "string", "title": "Protocol" }, "version": { "type": "string", "title": "Version" }, "agents": { "items": { "$ref": "#/components/schemas/ACPAgentListEntry" }, "type": "array", "title": "Agents" } }, "type": "object", "required": [ "protocol", "version", "agents" ], "title": "ACPDiscoveryResponse", "description": "Response for GET /.well-known/acp.json." }, "ACPRunCreateRequest": { "properties": { "input": { "type": "string", "title": "Input" }, "agent_id": { "type": "string", "title": "Agent Id", "default": "bernstein" }, "role": { "type": "string", "title": "Role", "default": "backend" } }, "type": "object", "required": [ "input" ], "title": "ACPRunCreateRequest", "description": "Body for POST /acp/v0/runs." }, "ACPRunResponse": { "properties": { "run_id": { "type": "string", "title": "Run Id" }, "bernstein_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bernstein Task Id" }, "input": { "type": "string", "title": "Input" }, "role": { "type": "string", "title": "Role" }, "status": { "type": "string", "title": "Status" }, "created_at": { "type": "number", "title": "Created At" }, "updated_at": { "type": "number", "title": "Updated At" } }, "type": "object", "required": [ "run_id", "input", "role", "status", "created_at", "updated_at" ], "title": "ACPRunResponse", "description": "ACP run in responses." }, "ApprovalDecisionRequest": { "properties": { "reason": { "type": "string", "title": "Reason", "default": "" } }, "type": "object", "title": "ApprovalDecisionRequest", "description": "Body for POST /approvals/{task_id}/approve or /reject." }, "ArchiveRecord": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "title": { "type": "string", "title": "Title" }, "role": { "type": "string", "title": "Role" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "status": { "type": "string", "title": "Status" }, "created_at": { "type": "number", "title": "Created At" }, "completed_at": { "type": "number", "title": "Completed At" }, "duration_seconds": { "type": "number", "title": "Duration Seconds" }, "result_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result Summary" }, "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cost Usd" }, "assigned_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned Agent" }, "owned_files": { "items": { "type": "string" }, "type": "array", "title": "Owned Files" }, "claimed_by_session": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claimed By Session" } }, "type": "object", "required": [ "task_id", "title", "role", "tenant_id", "status", "created_at", "completed_at", "duration_seconds", "result_summary", "cost_usd", "assigned_agent", "owned_files", "claimed_by_session" ], "title": "ArchiveRecord", "description": "Archive JSONL entry written when a task reaches a terminal state." }, "AuthProvidersResponse": { "properties": { "oidc_enabled": { "type": "boolean", "title": "Oidc Enabled", "default": false }, "saml_enabled": { "type": "boolean", "title": "Saml Enabled", "default": false }, "legacy_token_enabled": { "type": "boolean", "title": "Legacy Token Enabled", "default": false }, "device_flow_enabled": { "type": "boolean", "title": "Device Flow Enabled", "default": true } }, "type": "object", "title": "AuthProvidersResponse", "description": "Available authentication providers." }, "BatchClaimRequest": { "properties": { "task_ids": { "items": { "type": "string" }, "type": "array", "title": "Task Ids" }, "agent_id": { "type": "string", "title": "Agent Id" }, "claimed_by_session": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claimed By Session" } }, "type": "object", "required": [ "task_ids", "agent_id" ], "title": "BatchClaimRequest", "description": "Body for POST /tasks/claim-batch." }, "BatchClaimResponse": { "properties": { "claimed": { "items": { "type": "string" }, "type": "array", "title": "Claimed" }, "failed": { "items": { "type": "string" }, "type": "array", "title": "Failed" } }, "type": "object", "required": [ "claimed", "failed" ], "title": "BatchClaimResponse", "description": "Response for POST /tasks/claim-batch." }, "BatchCreateRequest": { "properties": { "tasks": { "items": { "$ref": "#/components/schemas/TaskCreate" }, "type": "array", "title": "Tasks" } }, "type": "object", "required": [ "tasks" ], "title": "BatchCreateRequest", "description": "Body for POST /tasks/batch." }, "BatchCreateResponse": { "properties": { "created": { "items": { "$ref": "#/components/schemas/TaskResponse" }, "type": "array", "title": "Created" }, "skipped_titles": { "items": { "type": "string" }, "type": "array", "title": "Skipped Titles" } }, "type": "object", "required": [ "created", "skipped_titles" ], "title": "BatchCreateResponse", "description": "Response for POST /tasks/batch." }, "BulletinMessageResponse": { "properties": { "agent_id": { "type": "string", "title": "Agent Id" }, "type": { "type": "string", "title": "Type" }, "content": { "type": "string", "title": "Content" }, "timestamp": { "type": "number", "title": "Timestamp" }, "cell_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cell Id" } }, "type": "object", "required": [ "agent_id", "type", "content", "timestamp", "cell_id" ], "title": "BulletinMessageResponse", "description": "Single bulletin message in responses." }, "BulletinPostRequest": { "properties": { "agent_id": { "type": "string", "title": "Agent Id" }, "type": { "type": "string", "enum": [ "alert", "blocker", "finding", "status", "dependency" ], "title": "Type", "default": "status" }, "content": { "type": "string", "title": "Content" }, "cell_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cell Id" } }, "type": "object", "required": [ "agent_id", "content" ], "title": "BulletinPostRequest", "description": "Body for POST /bulletin." }, "ClusterStatusResponse": { "properties": { "topology": { "type": "string", "title": "Topology" }, "total_nodes": { "type": "integer", "title": "Total Nodes" }, "online_nodes": { "type": "integer", "title": "Online Nodes" }, "offline_nodes": { "type": "integer", "title": "Offline Nodes" }, "total_capacity": { "type": "integer", "title": "Total Capacity" }, "available_slots": { "type": "integer", "title": "Available Slots" }, "active_agents": { "type": "integer", "title": "Active Agents" }, "nodes": { "items": { "$ref": "#/components/schemas/NodeResponse" }, "type": "array", "title": "Nodes" } }, "type": "object", "required": [ "topology", "total_nodes", "online_nodes", "offline_nodes", "total_capacity", "available_slots", "active_agents", "nodes" ], "title": "ClusterStatusResponse", "description": "Response for GET /cluster/status." }, "CompletionSignalSchema": { "properties": { "type": { "type": "string", "enum": [ "path_exists", "glob_exists", "test_passes", "file_contains", "llm_review", "llm_judge" ], "title": "Type" }, "value": { "type": "string", "title": "Value" } }, "type": "object", "required": [ "type", "value" ], "title": "CompletionSignalSchema", "description": "Pydantic schema for a single completion signal in API requests." }, "DependencyStatus": { "properties": { "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "title": "Status" }, "latency_ms": { "type": "number", "title": "Latency Ms", "default": 0.0 }, "detail": { "type": "string", "title": "Detail", "default": "" } }, "type": "object", "required": [ "name", "status" ], "title": "DependencyStatus", "description": "Status of a single dependency." }, "DeviceAuthorizeRequest": { "properties": { "user_code": { "type": "string", "title": "User Code" } }, "type": "object", "required": [ "user_code" ], "title": "DeviceAuthorizeRequest", "description": "Body for POST /auth/cli/authorize — authorize a device code." }, "DeviceCodeRequest": { "properties": { "client_name": { "type": "string", "title": "Client Name", "default": "bernstein-cli" } }, "type": "object", "title": "DeviceCodeRequest", "description": "Body for POST /auth/cli/device — initiate device auth flow." }, "DeviceCodeResponse": { "properties": { "device_code": { "type": "string", "title": "Device Code" }, "user_code": { "type": "string", "title": "User Code" }, "verification_uri": { "type": "string", "title": "Verification Uri" }, "expires_in": { "type": "integer", "title": "Expires In" }, "interval": { "type": "integer", "title": "Interval" } }, "type": "object", "required": [ "device_code", "user_code", "verification_uri", "expires_in", "interval" ], "title": "DeviceCodeResponse", "description": "Response for device code request." }, "DevicePollRequest": { "properties": { "device_code": { "type": "string", "title": "Device Code" }, "grant_type": { "type": "string", "title": "Grant Type", "default": "urn:ietf:params:oauth:grant-type:device_code" } }, "type": "object", "required": [ "device_code" ], "title": "DevicePollRequest", "description": "Body for POST /auth/cli/token — poll for device authorization." }, "DevicePollResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token", "default": "" }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Expires At" }, "refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refresh Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "Bearer" }, "status": { "type": "string", "title": "Status", "default": "pending" } }, "type": "object", "title": "DevicePollResponse", "description": "Response for device token poll." }, "GroupMappingEntry": { "properties": { "group": { "type": "string", "title": "Group" }, "role": { "type": "string", "title": "Role" } }, "type": "object", "required": [ "group", "role" ], "title": "GroupMappingEntry", "description": "A single group → role mapping." }, "GroupMappingsResponse": { "properties": { "mappings": { "items": { "$ref": "#/components/schemas/GroupMappingEntry" }, "type": "array", "title": "Mappings" } }, "type": "object", "required": [ "mappings" ], "title": "GroupMappingsResponse", "description": "Response for GET /auth/group-mappings." }, "GroupMappingsUpdateRequest": { "properties": { "mappings": { "items": { "$ref": "#/components/schemas/GroupMappingEntry" }, "type": "array", "title": "Mappings" } }, "type": "object", "required": [ "mappings" ], "title": "GroupMappingsUpdateRequest", "description": "Body for PUT /auth/group-mappings." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HealthDepsResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "uptime_s": { "type": "number", "title": "Uptime S" }, "timestamp": { "type": "number", "title": "Timestamp" }, "dependencies": { "items": { "$ref": "#/components/schemas/DependencyStatus" }, "type": "array", "title": "Dependencies" } }, "type": "object", "required": [ "status", "uptime_s", "timestamp" ], "title": "HealthDepsResponse", "description": "Full health response with dependency checks." }, "HealthResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "uptime_s": { "type": "number", "title": "Uptime S" }, "task_count": { "type": "integer", "title": "Task Count" }, "agent_count": { "type": "integer", "title": "Agent Count" }, "task_queue_depth": { "type": "integer", "title": "Task Queue Depth", "default": 0 }, "memory_mb": { "type": "number", "title": "Memory Mb", "default": 0.0 }, "restart_count": { "type": "integer", "title": "Restart Count", "default": 0 }, "is_readonly": { "type": "boolean", "title": "Is Readonly", "default": false }, "components": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object", "title": "Components" } }, "type": "object", "required": [ "status", "uptime_s", "task_count", "agent_count" ], "title": "HealthResponse", "description": "Response for GET /health." }, "HeartbeatRequest": { "properties": { "role": { "type": "string", "title": "Role", "default": "" }, "status": { "type": "string", "enum": [ "starting", "working", "idle", "dead" ], "title": "Status", "default": "working" } }, "type": "object", "title": "HeartbeatRequest", "description": "Body for POST /agents/{agent_id}/heartbeat." }, "HeartbeatResponse": { "properties": { "agent_id": { "type": "string", "title": "Agent Id" }, "acknowledged": { "type": "boolean", "title": "Acknowledged" }, "server_ts": { "type": "number", "title": "Server Ts" } }, "type": "object", "required": [ "agent_id", "acknowledged", "server_ts" ], "title": "HeartbeatResponse", "description": "Response for heartbeat." }, "ImpactResponse": { "properties": { "file_query": { "type": "string", "title": "File Query" }, "matched_files": { "items": { "type": "string" }, "type": "array", "title": "Matched Files" }, "impacted_files": { "items": { "type": "string" }, "type": "array", "title": "Impacted Files" }, "built_at": { "type": "string", "title": "Built At" } }, "type": "object", "required": [ "file_query", "matched_files", "impacted_files", "built_at" ], "title": "ImpactResponse", "description": "Response body for ``GET /graph/impact``." }, "ListApprovalsResponse": { "properties": { "pending": { "items": { "$ref": "#/components/schemas/PendingApproval" }, "type": "array", "title": "Pending" } }, "type": "object", "required": [ "pending" ], "title": "ListApprovalsResponse", "description": "Response for GET /approvals." }, "MergeOrderResponse": { "properties": { "repos": { "items": { "type": "string" }, "type": "array", "title": "Repos" } }, "type": "object", "required": [ "repos" ], "title": "MergeOrderResponse", "description": "Topological repository merge order." }, "NodeCapacitySchema": { "properties": { "max_agents": { "type": "integer", "title": "Max Agents", "default": 6 }, "available_slots": { "type": "integer", "title": "Available Slots", "default": 6 }, "active_agents": { "type": "integer", "title": "Active Agents", "default": 0 }, "gpu_available": { "type": "boolean", "title": "Gpu Available", "default": false }, "supported_models": { "items": { "type": "string" }, "type": "array", "title": "Supported Models" } }, "type": "object", "title": "NodeCapacitySchema", "description": "Advertised capacity of a cluster node." }, "NodeHeartbeatRequest": { "properties": { "capacity": { "anyOf": [ { "$ref": "#/components/schemas/NodeCapacitySchema" }, { "type": "null" } ] } }, "type": "object", "title": "NodeHeartbeatRequest", "description": "Body for POST /cluster/nodes/{node_id}/heartbeat." }, "NodeRegisterRequest": { "properties": { "name": { "type": "string", "title": "Name", "default": "" }, "url": { "type": "string", "title": "Url", "default": "" }, "capacity": { "$ref": "#/components/schemas/NodeCapacitySchema" }, "labels": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Labels" }, "cell_ids": { "items": { "type": "string" }, "type": "array", "title": "Cell Ids" } }, "type": "object", "title": "NodeRegisterRequest", "description": "Body for POST /cluster/nodes." }, "NodeResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "url": { "type": "string", "title": "Url" }, "status": { "type": "string", "title": "Status" }, "capacity": { "$ref": "#/components/schemas/NodeCapacitySchema" }, "last_heartbeat": { "type": "number", "title": "Last Heartbeat" }, "registered_at": { "type": "number", "title": "Registered At" }, "labels": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Labels" }, "cell_ids": { "items": { "type": "string" }, "type": "array", "title": "Cell Ids" } }, "type": "object", "required": [ "id", "name", "url", "status", "capacity", "last_heartbeat", "registered_at", "labels", "cell_ids" ], "title": "NodeResponse", "description": "Serialised node in API responses." }, "PaginatedSearchResponse": { "properties": { "tasks": { "items": { "$ref": "#/components/schemas/TaskResponse" }, "type": "array", "title": "Tasks" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "per_page": { "type": "integer", "title": "Per Page" }, "total_pages": { "type": "integer", "title": "Total Pages" }, "sort": { "type": "string", "title": "Sort" }, "order": { "type": "string", "title": "Order" }, "filters": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Filters" } }, "type": "object", "required": [ "tasks", "total", "page", "per_page", "total_pages", "sort", "order" ], "title": "PaginatedSearchResponse", "description": "Paginated task search response with metadata." }, "PaginatedTasksResponse": { "properties": { "tasks": { "items": { "$ref": "#/components/schemas/TaskResponse" }, "type": "array", "title": "Tasks" }, "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "tasks", "total", "limit", "offset" ], "title": "PaginatedTasksResponse", "description": "Paginated list of tasks with total count for cursor math." }, "PendingApproval": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "task_title": { "type": "string", "title": "Task Title" }, "session_id": { "type": "string", "title": "Session Id" }, "diff": { "type": "string", "title": "Diff", "default": "" }, "test_summary": { "type": "string", "title": "Test Summary", "default": "" } }, "type": "object", "required": [ "task_id", "task_title", "session_id" ], "title": "PendingApproval", "description": "A single pending approval request." }, "PlanDecisionRequest": { "properties": { "reason": { "type": "string", "title": "Reason", "default": "" } }, "type": "object", "title": "PlanDecisionRequest", "description": "Body for POST /plans/{plan_id}/approve or /reject." }, "ProgressEntry": { "properties": { "timestamp": { "type": "number", "title": "Timestamp" }, "message": { "type": "string", "title": "Message" }, "percent": { "type": "integer", "title": "Percent" } }, "type": "object", "required": [ "timestamp", "message", "percent" ], "title": "ProgressEntry", "description": "Single entry in a task's progress_log." }, "SnapshotEntry": { "properties": { "timestamp": { "type": "number", "title": "Timestamp" }, "files_changed": { "type": "integer", "title": "Files Changed" }, "tests_passing": { "type": "integer", "title": "Tests Passing" }, "errors": { "type": "integer", "title": "Errors" }, "last_file": { "type": "string", "title": "Last File" } }, "type": "object", "required": [ "timestamp", "files_changed", "tests_passing", "errors", "last_file" ], "title": "SnapshotEntry", "description": "A single machine-readable progress snapshot for stall detection." }, "TaskBlockRequest": { "properties": { "reason": { "type": "string", "title": "Reason", "default": "" } }, "type": "object", "title": "TaskBlockRequest", "description": "Body for POST /tasks/{task_id}/block." }, "TaskCancelRequest": { "properties": { "reason": { "type": "string", "title": "Reason", "default": "" } }, "type": "object", "title": "TaskCancelRequest", "description": "Body for POST /tasks/{task_id}/cancel." }, "TaskCompleteRequest": { "properties": { "result_summary": { "type": "string", "title": "Result Summary" } }, "type": "object", "required": [ "result_summary" ], "title": "TaskCompleteRequest", "description": "Body for POST /tasks/{task_id}/complete." }, "TaskCountsResponse": { "properties": { "open": { "type": "integer", "title": "Open", "default": 0 }, "claimed": { "type": "integer", "title": "Claimed", "default": 0 }, "done": { "type": "integer", "title": "Done", "default": 0 }, "failed": { "type": "integer", "title": "Failed", "default": 0 }, "blocked": { "type": "integer", "title": "Blocked", "default": 0 }, "cancelled": { "type": "integer", "title": "Cancelled", "default": 0 }, "total": { "type": "integer", "title": "Total", "default": 0 } }, "type": "object", "title": "TaskCountsResponse", "description": "Lightweight status counts — no task bodies." }, "TaskCreate": { "properties": { "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "role": { "type": "string", "title": "Role", "default": "auto" }, "tenant_id": { "type": "string", "title": "Tenant Id", "default": "default" }, "priority": { "type": "integer", "title": "Priority", "default": 2 }, "scope": { "type": "string", "title": "Scope", "default": "medium" }, "complexity": { "type": "string", "title": "Complexity", "default": "medium" }, "eu_ai_act_risk": { "type": "string", "title": "Eu Ai Act Risk", "default": "minimal" }, "approval_required": { "type": "boolean", "title": "Approval Required", "default": false }, "risk_level": { "type": "string", "title": "Risk Level", "default": "low" }, "estimated_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Minutes" }, "depends_on": { "items": { "type": "string" }, "type": "array", "title": "Depends On" }, "parent_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Task Id" }, "depends_on_repo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Depends On Repo" }, "owned_files": { "items": { "type": "string" }, "type": "array", "title": "Owned Files" }, "cell_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cell Id" }, "repo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repo" }, "task_type": { "type": "string", "title": "Task Type", "default": "standard" }, "upgrade_details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Upgrade Details" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Effort" }, "batch_eligible": { "type": "boolean", "title": "Batch Eligible", "default": false }, "completion_signals": { "items": { "$ref": "#/components/schemas/CompletionSignalSchema" }, "type": "array", "title": "Completion Signals" }, "slack_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Slack Context" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "deadline": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Deadline" }, "parent_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Session Id" }, "parent_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Context" } }, "type": "object", "required": [ "title", "description" ], "title": "TaskCreate", "description": "Body for POST /tasks." }, "TaskDetailResponse": { "properties": { "task": { "$ref": "#/components/schemas/TaskResponse" }, "log_tail": { "type": "string", "title": "Log Tail" }, "log_size": { "type": "integer", "title": "Log Size" }, "progress_entries": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Progress Entries" }, "agent_status": { "type": "string", "title": "Agent Status", "default": "" } }, "type": "object", "required": [ "task", "log_tail", "log_size" ], "title": "TaskDetailResponse", "description": "Detailed task view including log tail and progress." }, "TaskFailRequest": { "properties": { "reason": { "type": "string", "title": "Reason", "default": "" } }, "type": "object", "title": "TaskFailRequest", "description": "Body for POST /tasks/{task_id}/fail." }, "TaskPatchRequest": { "properties": { "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" }, "priority": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Priority" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" } }, "type": "object", "title": "TaskPatchRequest", "description": "Body for PATCH /tasks/{task_id} — manager corrections." }, "TaskProgressRequest": { "properties": { "message": { "type": "string", "title": "Message", "default": "" }, "percent": { "type": "integer", "title": "Percent", "default": 0 }, "files_changed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Files Changed" }, "tests_passing": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tests Passing" }, "errors": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Errors" }, "last_file": { "type": "string", "title": "Last File", "default": "" } }, "type": "object", "title": "TaskProgressRequest", "description": "Body for POST /tasks/{task_id}/progress." }, "TaskResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "role": { "type": "string", "title": "Role" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "priority": { "type": "integer", "title": "Priority" }, "scope": { "type": "string", "title": "Scope" }, "complexity": { "type": "string", "title": "Complexity" }, "eu_ai_act_risk": { "type": "string", "title": "Eu Ai Act Risk" }, "approval_required": { "type": "boolean", "title": "Approval Required" }, "risk_level": { "type": "string", "title": "Risk Level" }, "estimated_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Minutes" }, "status": { "type": "string", "title": "Status" }, "depends_on": { "items": { "type": "string" }, "type": "array", "title": "Depends On" }, "parent_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Task Id" }, "depends_on_repo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Depends On Repo" }, "owned_files": { "items": { "type": "string" }, "type": "array", "title": "Owned Files" }, "assigned_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned Agent" }, "result_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result Summary" }, "cell_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cell Id" }, "repo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repo" }, "task_type": { "type": "string", "title": "Task Type" }, "upgrade_details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Upgrade Details" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Effort" }, "batch_eligible": { "type": "boolean", "title": "Batch Eligible", "default": false }, "completion_signals": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array", "title": "Completion Signals" }, "slack_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Slack Context" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "created_at": { "type": "number", "title": "Created At" }, "claimed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Claimed At" }, "deadline": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Deadline" }, "progress_log": { "items": { "$ref": "#/components/schemas/ProgressEntry" }, "type": "array", "title": "Progress Log" }, "version": { "type": "integer", "title": "Version", "default": 1 }, "parent_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Session Id" } }, "type": "object", "required": [ "id", "title", "description", "role", "tenant_id", "priority", "scope", "complexity", "eu_ai_act_risk", "approval_required", "risk_level", "estimated_minutes", "status", "depends_on", "parent_task_id", "depends_on_repo", "owned_files", "assigned_agent", "result_summary", "cell_id", "repo", "task_type", "upgrade_details", "model", "effort", "created_at" ], "title": "TaskResponse", "description": "Serialised task returned by every task endpoint." }, "TaskSelfCreate": { "properties": { "parent_task_id": { "type": "string", "title": "Parent Task Id" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "role": { "type": "string", "title": "Role", "default": "auto" }, "priority": { "type": "integer", "title": "Priority", "default": 2 }, "scope": { "type": "string", "title": "Scope", "default": "medium" }, "complexity": { "type": "string", "title": "Complexity", "default": "medium" }, "estimated_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Minutes" }, "depends_on": { "items": { "type": "string" }, "type": "array", "title": "Depends On" }, "owned_files": { "items": { "type": "string" }, "type": "array", "title": "Owned Files" } }, "type": "object", "required": [ "parent_task_id", "title", "description" ], "title": "TaskSelfCreate", "description": "Body for POST /tasks/self-create — agent-initiated subtask creation.\n\nAgents use this to decompose work into subtasks during execution.\nThe parent_task_id is required and links the new subtask to the calling\nagent's current task." }, "TaskStealAction": { "properties": { "donor_node_id": { "type": "string", "title": "Donor Node Id" }, "receiver_node_id": { "type": "string", "title": "Receiver Node Id" }, "task_ids": { "items": { "type": "string" }, "type": "array", "title": "Task Ids" } }, "type": "object", "required": [ "donor_node_id", "receiver_node_id", "task_ids" ], "title": "TaskStealAction", "description": "A single steal action: move tasks from donor to receiver." }, "TaskStealRequest": { "properties": { "queue_depths": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Queue Depths" } }, "type": "object", "title": "TaskStealRequest", "description": "Body for POST /cluster/steal — report queue depths and request rebalancing." }, "TaskStealResponse": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/TaskStealAction" }, "type": "array", "title": "Actions" }, "total_stolen": { "type": "integer", "title": "Total Stolen" } }, "type": "object", "required": [ "actions", "total_stolen" ], "title": "TaskStealResponse", "description": "Response for POST /cluster/steal." }, "TaskWaitForSubtasksRequest": { "properties": { "subtask_count": { "type": "integer", "title": "Subtask Count", "default": 0 } }, "type": "object", "title": "TaskWaitForSubtasksRequest", "description": "Body for POST /tasks/{task_id}/wait-for-subtasks." }, "UserProfileResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "email": { "type": "string", "title": "Email" }, "display_name": { "type": "string", "title": "Display Name" }, "role": { "type": "string", "title": "Role" }, "sso_provider": { "type": "string", "title": "Sso Provider" }, "sso_groups": { "items": { "type": "string" }, "type": "array", "title": "Sso Groups" }, "permissions": { "items": { "type": "string" }, "type": "array", "title": "Permissions" } }, "type": "object", "required": [ "id", "email", "display_name", "role", "sso_provider", "sso_groups", "permissions" ], "title": "UserProfileResponse", "description": "Response for GET /auth/me." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WebhookTaskCreate": { "properties": { "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "role": { "type": "string", "title": "Role", "default": "backend" }, "tenant_id": { "type": "string", "title": "Tenant Id", "default": "default" }, "priority": { "type": "integer", "title": "Priority", "default": 2 }, "scope": { "type": "string", "title": "Scope", "default": "medium" }, "complexity": { "type": "string", "title": "Complexity", "default": "medium" }, "eu_ai_act_risk": { "type": "string", "title": "Eu Ai Act Risk", "default": "minimal" }, "approval_required": { "type": "boolean", "title": "Approval Required", "default": false }, "risk_level": { "type": "string", "title": "Risk Level", "default": "low" }, "estimated_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Minutes" }, "depends_on": { "items": { "type": "string" }, "type": "array", "title": "Depends On" }, "parent_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Task Id" }, "depends_on_repo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Depends On Repo" }, "owned_files": { "items": { "type": "string" }, "type": "array", "title": "Owned Files" }, "cell_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cell Id" }, "repo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repo" }, "task_type": { "type": "string", "title": "Task Type", "default": "standard" }, "upgrade_details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Upgrade Details" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Effort" }, "batch_eligible": { "type": "boolean", "title": "Batch Eligible", "default": false }, "completion_signals": { "items": { "$ref": "#/components/schemas/CompletionSignalSchema" }, "type": "array", "title": "Completion Signals" }, "slack_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Slack Context" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "deadline": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Deadline" }, "parent_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Session Id" }, "parent_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Context" } }, "type": "object", "required": [ "title", "description" ], "title": "WebhookTaskCreate", "description": "Body for POST /webhook." }, "WebhookTaskResponse": { "properties": { "task": { "$ref": "#/components/schemas/TaskResponse" } }, "type": "object", "required": [ "task" ], "title": "WebhookTaskResponse", "description": "Serialized task returned by POST /webhook." }, "WorkspaceRepoResponse": { "properties": { "name": { "type": "string", "title": "Name" }, "path": { "type": "string", "title": "Path" }, "branch": { "type": "string", "title": "Branch" }, "clean": { "type": "boolean", "title": "Clean" }, "ahead": { "type": "integer", "title": "Ahead" }, "behind": { "type": "integer", "title": "Behind" } }, "type": "object", "required": [ "name", "path", "branch", "clean", "ahead", "behind" ], "title": "WorkspaceRepoResponse", "description": "Workspace repository status entry." }, "WorkspaceResponse": { "properties": { "repos": { "items": { "$ref": "#/components/schemas/WorkspaceRepoResponse" }, "type": "array", "title": "Repos" } }, "type": "object", "required": [ "repos" ], "title": "WorkspaceResponse", "description": "Workspace repository status payload." } } } }