{ "openapi": "3.1.0", "info": { "title": "Robot BT Task API", "version": "1.1.0", "description": "Versioned v1 single-item and v2 ordered multi-item coordination (maximum20). Control ACK is not physical stop; 64 KiB maximum JSON." }, "servers": [ { "url": "http://127.0.0.1:8088" } ], "paths": { "/healthz": { "get": { "operationId": "health", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/capabilities": { "get": { "operationId": "capabilities", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tasks": { "post": { "operationId": "submitTask", "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRequest" } } } } } }, "/v1/tasks/{task_id}": { "get": { "operationId": "getTask", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/tasks/{task_id}/events": { "get": { "operationId": "getEvents", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ] } }, "/v1/tasks/{task_id}/cancel": { "post": { "operationId": "cancelTask", "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/tasks/{task_id}/pause": { "post": { "operationId": "pauseTask", "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/tasks/{task_id}/resume": { "post": { "operationId": "resumeTask", "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/tasks/{task_id}/clarifications": { "post": { "operationId": "answerClarification", "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Clarification" } } } } } }, "/v1/tasks/{task_id}/interventions": { "post": { "operationId": "reconcileTask", "security": [ { "OperatorAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "default": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intervention" } } } } } } }, "components": { "schemas": { "KnownInfo": { "oneOf": [ { "$ref": "#/components/schemas/KnownInfoV1" }, { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "target_name", "quantity", "source_location" ], "properties": { "target_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "source_location": { "type": "string", "minLength": 1, "maxLength": 200 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20 } } } }, "destination": { "type": "string", "minLength": 1, "maxLength": 200 } }, "description": "Ordered items; sum(quantity)<=20 is also checked in code." } ] }, "TaskRequest": { "type": "object", "additionalProperties": false, "required": [ "client_request_id", "robot_id", "instruction" ], "properties": { "client_request_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "robot_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "instruction": { "type": "string", "minLength": 1, "maxLength": 1000 }, "known_info": { "$ref": "#/components/schemas/KnownInfo" }, "client_created_at": { "type": "number", "minimum": 0 } } }, "Error": { "type": "object", "required": [ "error_code", "message" ], "properties": { "error_code": { "type": "string" }, "message": { "type": "string" } } }, "Clarification": { "type": "object", "additionalProperties": false, "required": [ "question_id", "task_revision", "known_info" ], "properties": { "question_id": { "type": "string" }, "task_revision": { "type": "integer", "minimum": 1 }, "known_info": { "$ref": "#/components/schemas/KnownInfo" } } }, "Intervention": { "type": "object", "additionalProperties": false, "required": [ "run_id", "evidence_ref", "resolution" ], "properties": { "run_id": { "type": "string" }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 512 }, "resolution": { "type": "string", "enum": [ "cancel_task" ] } } }, "TaskView": { "type": "object", "required": [ "task_id", "robot_id", "task_revision", "status", "status_version", "completed_quantity" ], "properties": { "task_id": { "type": "string", "format": "uuid" }, "robot_id": { "type": "string" }, "task_revision": { "type": "integer" }, "planning_generation": { "type": "integer" }, "plan_version": { "type": "integer" }, "run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "RECEIVED", "QUEUED", "PLANNING", "NEEDS_CLARIFICATION", "READY", "EXECUTING", "PAUSING", "PAUSED", "CANCELING", "INTERVENTION_REQUIRED", "SUCCEEDED", "FAILED", "CANCELED", "EXPIRED" ] }, "status_version": { "type": "integer" }, "stage": { "type": "string" }, "error_code": { "type": "string" }, "completed_quantity": { "type": "integer", "minimum": 0, "maximum": 20 }, "stop_confirmed": { "type": "boolean" }, "accepted_at": { "type": "number" }, "updated_at": { "type": "number" }, "deduplicated": { "type": "boolean" }, "question": { "type": [ "object", "null" ] }, "plan": { "type": [ "object", "null" ] }, "context": { "type": [ "object", "null" ] }, "requested_quantity": { "type": "integer", "minimum": 1, "maximum": 20 }, "active_item_index": { "type": "integer", "minimum": 0, "maximum": 19 } } }, "KnownInfoV1": { "type": "object", "additionalProperties": false, "properties": { "target_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "quantity": { "type": "integer", "enum": [ 1 ] }, "source_location": { "type": "string", "minLength": 1, "maxLength": 200 }, "destination": { "type": "string", "minLength": 1, "maxLength": 200 } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" }, "OperatorAuth": { "type": "http", "scheme": "bearer", "description": "Separate operator credential; evidence is resolved by trusted backend." } } } }