{ "openapi": "3.1.0", "info": { "title": "FlyTrustAgent Runtime API", "version": "0.1.0", "description": "One trusted operator realm, project-scoped tokens, explicit capability execution. Response verification is separate from business outcome." }, "servers": [ { "url": "https://api.flytrust-agent.io.vn/v1", "description": "Versioned API gateway" }, { "url": "https://api.flytrust-agent.io.vn/api/runtime/v1", "description": "RuntimeClient SDK compatibility" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "message" ] }, "ModelValue": { "type": [ "string", "number", "boolean", "null" ] }, "Condition": { "oneOf": [ { "$ref": "#/components/schemas/Predicate" }, { "$ref": "#/components/schemas/ConditionGroup" } ] }, "Predicate": { "type": "object", "properties": { "kind": { "const": "predicate" }, "variableId": { "type": "string" }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "isUnknown", "isKnown" ] }, "value": { "$ref": "#/components/schemas/ModelValue" } }, "required": [ "kind", "variableId", "operator" ] }, "ConditionGroup": { "type": "object", "properties": { "kind": { "const": "group" }, "combinator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" } } }, "required": [ "kind", "combinator", "conditions" ] }, "AgentModel": { "type": "object", "properties": { "schemaVersion": { "const": "1.0.0" }, "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "updatedAt": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "user": { "type": "string" }, "goal": { "type": "string" }, "completionCriteria": { "type": "string" } }, "required": [ "id", "name", "role", "user", "goal", "completionCriteria" ] }, "scope": { "type": "object", "properties": { "allowedActions": { "type": "string" }, "limits": { "type": "string" }, "askUserWhen": { "type": "string" } }, "required": [ "allowedActions", "limits", "askUserWhen" ] }, "variables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "input", "memory" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "text", "choice" ] }, "unit": { "type": "string" }, "defaultValue": { "$ref": "#/components/schemas/ModelValue" }, "choices": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "name", "kind", "type", "defaultValue", "source" ] } }, "states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "meaning": { "type": "string" }, "isStart": { "type": "boolean" }, "isFinal": { "type": "boolean" }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, "required": [ "id", "name", "meaning", "isStart", "isFinal", "position" ] } }, "transitions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "fromStateId": { "type": "string" }, "toStateId": { "type": "string" }, "priority": { "type": "integer", "minimum": 0 }, "actionId": { "type": "string" }, "condition": { "$ref": "#/components/schemas/Condition" } }, "required": [ "id", "name", "fromStateId", "toStateId", "priority", "condition" ] } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "string" } }, "simulatedResult": { "type": "string" }, "memoryEffects": { "type": "array", "items": { "type": "object", "properties": { "variableId": { "type": "string" }, "value": { "$ref": "#/components/schemas/ModelValue" } }, "required": [ "variableId", "value" ] } } }, "required": [ "id", "name", "description", "inputs", "simulatedResult", "memoryEffects" ] } }, "scenarios": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ModelValue" } }, "initialMemory": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ModelValue" } }, "expectedStateId": { "type": "string" }, "expectedPath": { "type": "array", "items": { "type": "string" } }, "expectedResult": { "type": "string" } }, "required": [ "id", "name", "description", "inputs", "initialMemory", "expectedStateId", "expectedPath", "expectedResult" ] } } }, "required": [ "schemaVersion", "id", "name", "description", "revision", "updatedAt", "agent", "scope", "variables", "states", "transitions", "actions", "scenarios" ] }, "ModelWrite": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/AgentModel" }, "expectedRevision": { "type": "integer", "description": "Required when updating. Compare-and-set against the stored revision." } }, "required": [ "document" ] }, "Model": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "revision": { "type": "integer" }, "schemaVersion": { "type": "string" }, "document": { "$ref": "#/components/schemas/AgentModel" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "revision", "document" ] }, "Capability": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "path": { "type": "string", "description": "Origin-relative path, e.g. /api/tasks. Query and traversal prohibited." }, "sideEffect": { "type": "boolean" }, "approval": { "type": "string", "enum": [ "NONE", "RISK_BASED", "ALWAYS" ] }, "idempotent": { "type": "boolean" }, "timeoutMs": { "type": "integer", "minimum": 100, "maximum": 60000 }, "inputSchema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "object", "array" ] }, "required": { "type": "boolean" } }, "required": [ "type", "required" ] } } }, "required": [ "name", "method", "path" ] }, "ProjectWrite": { "type": "object", "properties": { "name": { "type": "string" }, "adapter": { "type": "string", "enum": [ "HTTP_JSON", "LOCAL_ECHO" ] }, "baseUrl": { "type": "string", "description": "HTTP(S) origin. Registered by ADMIN only." }, "healthPath": { "type": "string" }, "authSecretEnv": { "type": "string", "description": "Server environment variable name, never the secret value." }, "enabled": { "type": "boolean" }, "expectedRevision": { "type": "integer" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } } }, "required": [ "name", "adapter", "capabilities" ] }, "Project": { "allOf": [ { "$ref": "#/components/schemas/ProjectWrite" }, { "type": "object", "properties": { "id": { "type": "string" }, "revision": { "type": "integer" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "secretConfigured": { "type": "boolean" } }, "required": [ "id", "revision" ] } ] }, "Expectation": { "type": "object", "properties": { "field": { "type": "string" }, "equals": {}, "statusCode": { "type": "integer", "minimum": 200, "maximum": 299 } }, "required": [ "field", "equals" ] }, "Step": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "projectId": { "type": "string" }, "capability": { "type": "string" }, "actionId": { "type": "string" }, "input": { "type": "object", "additionalProperties": true }, "dependsOn": { "type": "array", "items": { "type": "string" } }, "inputBindings": { "type": "object", "additionalProperties": { "type": "object", "properties": { "stepId": { "type": "string" }, "field": { "type": "string" } }, "required": [ "stepId", "field" ] } }, "expectation": { "$ref": "#/components/schemas/Expectation" } }, "required": [ "id", "name", "projectId", "capability" ] }, "PlanWrite": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "modelId": { "type": "string" }, "modelRevision": { "type": "integer" }, "scenarioId": { "type": "string" }, "planningInputs": { "type": "object", "additionalProperties": true }, "mode": { "type": "string", "enum": [ "DRY_RUN", "LIVE" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Step" }, "maxItems": 100 } }, "required": [ "name", "modelId", "modelRevision", "steps" ] }, "Plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "modelId": { "type": "string" }, "modelRevision": { "type": "integer" }, "modelSnapshot": { "$ref": "#/components/schemas/Model" }, "projectSnapshots": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Step" } }, "mode": { "type": "string", "enum": [ "DRY_RUN", "LIVE" ] }, "status": { "type": "string", "enum": [ "READY", "INVALID" ] }, "validationErrors": { "type": "array", "items": { "type": "string" } }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "status", "steps" ] }, "RunStart": { "type": "object", "properties": { "planId": { "type": "string" } }, "required": [ "planId" ] }, "Run": { "type": "object", "properties": { "id": { "type": "string" }, "planId": { "type": "string" }, "planSnapshot": { "$ref": "#/components/schemas/Plan" }, "status": { "type": "string", "enum": [ "READY", "RUNNING", "WAITING_APPROVAL", "RECOVERY_REQUIRED", "COMPLETED", "FAILED", "CANCELLED" ] }, "steps": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "approvalId": { "type": "string" }, "error": { "type": "string" }, "requestedBy": { "type": "string" }, "idempotencyKey": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "completedAt": { "type": "string" } }, "required": [ "id", "planId", "status", "steps" ] }, "SimulationRequest": { "type": "object", "properties": { "scenarioId": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": true } }, "required": [ "scenarioId" ] }, "CompileRequest": { "type": "object", "properties": { "name": { "type": "string" }, "scenarioId": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": true }, "mode": { "type": "string", "enum": [ "DRY_RUN", "LIVE" ] }, "actionBindings": { "type": "object", "additionalProperties": { "type": "object", "properties": { "projectId": { "type": "string" }, "capability": { "type": "string" }, "input": { "type": "object", "additionalProperties": true }, "inputVariables": { "type": "object", "additionalProperties": { "type": "string" } }, "expectation": { "$ref": "#/components/schemas/Expectation" } }, "required": [ "projectId", "capability" ] } } }, "required": [ "scenarioId", "actionBindings" ] }, "Reason": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] }, "Decision": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "APPROVED", "REJECTED" ] }, "reason": { "type": "string" } }, "required": [ "decision", "reason" ] }, "Reconcile": { "type": "object", "properties": { "resolution": { "type": "string", "enum": [ "CONFIRMED_COMPLETED", "CONFIRMED_NOT_EXECUTED", "ABANDON" ] }, "evidence": { "type": "string" }, "output": { "type": "object", "additionalProperties": true } }, "required": [ "resolution", "evidence" ] }, "Approval": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "planId": { "type": "string" }, "stepId": { "type": "string" }, "projectId": { "type": "string" }, "capability": { "type": "string" }, "inputSnapshot": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED" ] }, "requestedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "decidedAt": { "type": "string" }, "decidedBy": { "type": "string" }, "decisionReason": { "type": "string" } }, "required": [ "id", "runId", "stepId", "status", "inputSnapshot", "expiresAt" ] }, "ModelPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "total": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "nextOffset" ] }, "ProjectPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "total": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "nextOffset" ] }, "PlanPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "total": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "nextOffset" ] }, "RunPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "total": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "nextOffset" ] }, "ApprovalPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" } }, "total": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "nextOffset" ] } } }, "paths": { "/health": { "get": { "summary": "Read public runtime health", "operationId": "get_health", "parameters": [], "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/openapi.json": { "get": { "summary": "Read API contract", "operationId": "get_openapi_json", "parameters": [], "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/metrics": { "get": { "summary": "ADMIN runtime metrics", "operationId": "get_metrics", "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/models": { "get": { "summary": "List models", "operationId": "get_models", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPage" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/models/{id}": { "get": { "summary": "Read model", "operationId": "get_models__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "OPERATOR save full model revision", "operationId": "put_models__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelWrite" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/models/{id}/validate": { "post": { "summary": "Validate stored model", "operationId": "post_models__id__validate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/models/{id}/simulate": { "post": { "summary": "Deterministic scenario simulation", "operationId": "post_models__id__simulate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/models/{id}/compile-plan": { "post": { "summary": "Compile modeled actions into an explicit plan", "operationId": "post_models__id__compile_plan", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileRequest" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects": { "get": { "summary": "List scoped project connections", "operationId": "get_projects", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPage" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}": { "put": { "summary": "ADMIN register or update project", "operationId": "put_projects__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectWrite" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/test": { "post": { "summary": "OPERATOR send signed health request", "operationId": "post_projects__id__test", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plans": { "get": { "summary": "List scoped plans", "operationId": "get_plans", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanPage" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "OPERATOR validate and freeze an execution plan", "operationId": "post_plans", "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanWrite" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plans/{id}": { "get": { "summary": "Read immutable plan", "operationId": "get_plans__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/runs": { "get": { "summary": "List scoped runs", "operationId": "get_runs", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPage" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "OPERATOR submit idempotent asynchronous run", "operationId": "post_runs", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 150 }, "description": "Scoped to actor; reuse on different plan returns 409." } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStart" } } } }, "responses": { "202": { "description": "Accepted. Poll GET /runs/{id}; external execution is asynchronous.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/runs/{id}": { "get": { "summary": "Read run", "operationId": "get_runs__id_", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/runs/{id}/resume": { "post": { "summary": "OPERATOR resume recovered ready run", "operationId": "post_runs__id__resume", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted. Poll GET /runs/{id}; external execution is asynchronous.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/runs/{id}/cancel": { "post": { "summary": "OPERATOR request cancellation", "operationId": "post_runs__id__cancel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/runs/{id}/reconcile": { "post": { "summary": "APPROVER reconcile uncertain external execution", "operationId": "post_runs__id__reconcile", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reconcile" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/approvals": { "get": { "summary": "List scoped approvals", "operationId": "get_approvals", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalPage" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/approvals/{id}/decision": { "post": { "summary": "APPROVER decide a pending approval (expires in 1 hour)", "operationId": "post_approvals__id__decision", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Decision" } } } }, "responses": { "202": { "description": "Accepted. Poll GET /runs/{id}; external execution is asynchronous.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audit": { "get": { "summary": "ADMIN read audit chain and integrity status", "operationId": "get_audit", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }