{ "openapi": "3.1.0", "info": { "title": "Oblive Backend API", "version": "0.1.0", "description": "Local API for Oblive business runner backend resources." }, "servers": [ { "url": "http://localhost:3000", "description": "Default local backend API server." } ], "tags": [ { "name": "Organizations" }, { "name": "Organization Onboarding" }, { "name": "Agent Profiles" }, { "name": "Chats" }, { "name": "Messages" }, { "name": "Organization Context" }, { "name": "Internal Chat" }, { "name": "Internal Runs" }, { "name": "Internal Agent" }, { "name": "Human Inbox" }, { "name": "Tasks" }, { "name": "Task Dependencies" }, { "name": "Run Requests" }, { "name": "Runs" }, { "name": "Durability" }, { "name": "Schedules" }, { "name": "Actions" }, { "name": "Integrations" } ], "components": { "securitySchemes": { "agentServiceToken": { "type": "http", "scheme": "bearer", "bearerFormat": "service token", "description": "Token used by trusted agent runtimes." }, "agentExecutionCapability": { "type": "http", "scheme": "bearer", "bearerFormat": "execution capability", "description": "Short-lived capability scoped to one organization, profile, and task run or chat turn." }, "integrationGatewayCapability": { "type": "http", "scheme": "bearer", "bearerFormat": "execution capability", "description": "Short-lived capability scoped to one organization, profile, integration, and execution." } } }, "paths": { "/organization-onboardings": { "post": { "operationId": "createOrganizationOnboarding", "summary": "Create an organization onboarding shell", "tags": [ "Organization Onboarding" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "slug", "timezone", "departments" ], "properties": { "name": { "type": "string", "example": "Acme" }, "slug": { "type": "string", "example": "acme" }, "timezone": { "type": "string", "example": "Asia/Kolkata" }, "departments": { "type": "array", "items": { "type": "string", "enum": [ "growth", "engineering", "support" ] } } } } } } }, "responses": { "201": { "description": "Organization onboarding created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "description": "Durable organization onboarding state derived from PostgreSQL and object storage.", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Organization onboarding created.", "data": {}, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "409": { "description": "Organization slug already exists.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "An organization with this slug already exists.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/onboarding": { "get": { "operationId": "getOrganizationOnboarding", "summary": "Get the current organization onboarding state", "tags": [ "Organization Onboarding" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization onboarding found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "description": "Durable organization onboarding state derived from PostgreSQL and object storage.", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Organization onboarding found.", "data": {}, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "404": { "description": "Organization onboarding not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Organization not found.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } } } }, "delete": { "operationId": "discardOrganizationOnboarding", "summary": "Discard incomplete organization onboarding", "tags": [ "Organization Onboarding" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization onboarding discarded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "description": "Durable organization onboarding state derived from PostgreSQL and object storage.", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Organization onboarding discarded.", "data": {}, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "409": { "description": "Onboarding state does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Onboarding state does not permit this action.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/onboarding/sources/{sourceId}": { "put": { "operationId": "putOrganizationOnboardingSource", "summary": "Store one organization onboarding source", "description": "Accepts one raw supported source with a maximum size of 50 MB.", "tags": [ "Organization Onboarding" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "department", "in": "query", "required": false, "description": "Department evidence scope. Omit for organization-wide evidence.", "schema": { "type": "string", "enum": [ "growth", "engineering", "support" ] } }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "file", "markdown" ] } }, { "name": "fileName", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "mediaType", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "201": { "description": "Onboarding source stored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "description": "Stored onboarding source manifest.", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Onboarding source stored.", "data": {}, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "400": { "description": "Invalid source metadata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "413": { "description": "Source exceeds 50 MB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 413, "message": "Source files cannot exceed 50 MB.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "415": { "description": "Source type is unsupported.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 415, "message": "Source type is unsupported.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } } } }, "delete": { "operationId": "deleteOrganizationOnboardingSource", "summary": "Delete an onboarding source before kickoff", "tags": [ "Organization Onboarding" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Onboarding source deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "description": "Durable organization onboarding state derived from PostgreSQL and object storage.", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Onboarding source deleted.", "data": {}, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "409": { "description": "Onboarding state does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Onboarding state does not permit this action.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/onboarding/start": { "post": { "operationId": "startOrganizationOnboarding", "summary": "Start the organization onboarding chat", "tags": [ "Organization Onboarding" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization onboarding started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "description": "Durable organization onboarding state derived from PostgreSQL and object storage.", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Organization onboarding started.", "data": {}, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "409": { "description": "Onboarding state does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Onboarding state does not permit this action.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/onboarding/complete": { "post": { "operationId": "completeOrganizationOnboarding", "summary": "Activate a reviewed organization", "tags": [ "Organization Onboarding" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization onboarding completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "description": "Durable organization onboarding state derived from PostgreSQL and object storage.", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Organization onboarding completed.", "data": {}, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } }, "409": { "description": "Onboarding state does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Onboarding state does not permit this action.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T08:00:00.000Z" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reviewSha256", "allowWarnings" ], "properties": { "reviewSha256": { "type": "string", "example": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "allowWarnings": { "type": "boolean", "example": false } } } } } } } }, "/organizations": { "get": { "operationId": "listOrganizations", "summary": "List organizations", "tags": [ "Organizations" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Cursor returned by the previous list call." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 }, "description": "Maximum number of organizations to return." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "id", "slug", "name", "createdAt", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Organizations listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "name", "status", "rootUri", "authorizationEpoch", "config", "constraints", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Stable organization slug." }, "name": { "type": "string", "description": "Human-readable organization name." }, "status": { "type": "string", "enum": [ "onboarding", "active", "paused" ] }, "onboardedAt": { "type": "string", "format": "date-time", "nullable": true }, "rootUri": { "type": "string", "description": "Root URI for organization memory." }, "authorizationEpoch": { "type": "integer", "example": 1 }, "config": { "type": "object", "required": [ "timezone", "departments", "limits", "storageRootUri" ], "properties": { "timezone": { "type": "string", "description": "IANA timezone used by the organization." }, "departments": { "type": "object", "required": [ "growth", "engineering", "support" ], "properties": { "growth": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "engineering": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "support": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } } } }, "limits": { "type": "object", "required": [ "maxConcurrentRuns", "maxDailyActions", "maxTaskDepth", "maxPlanOperations", "maxInitiativeDescendants" ], "properties": { "maxConcurrentRuns": { "type": "integer", "example": 3 }, "maxDailyActions": { "type": "integer", "example": 100, "description": "Organization-local daily review threshold. Reaching it opens one non-blocking notification; task action budgets remain the hard limit." }, "maxTaskDepth": { "type": "integer", "example": 4 }, "maxPlanOperations": { "type": "integer", "example": 25, "description": "Maximum create and reopen operations accepted in one plan." }, "maxInitiativeDescendants": { "type": "integer", "example": 100, "description": "Maximum durable descendants allowed under one initiative." } } }, "storageRootUri": { "type": "string", "description": "Root URI for organization storage." } } }, "constraints": { "type": "object", "required": [ "allowedIntegrations", "blockedDomains", "approvalRequiredForRisk" ], "properties": { "allowedIntegrations": { "type": "array", "items": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "description": "Integration provider key." }, "externalId": { "type": "string", "description": "Provider-owned identifier." }, "uri": { "type": "string", "description": "Provider resource URI." } } } }, "blockedDomains": { "type": "array", "items": { "type": "string" } }, "approvalRequiredForRisk": { "type": "array", "items": { "type": "string", "enum": [ "low", "reversible", "external", "high" ] } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "example": { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } }, "pagination": { "type": "object", "required": [ "cursor", "limit", "nextCursor", "previousCursor", "hasNextPage", "hasPreviousPage" ], "properties": { "cursor": { "type": "string", "nullable": true }, "limit": { "type": "integer" }, "nextCursor": { "type": "string", "nullable": true }, "previousCursor": { "type": "string", "nullable": true }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } } } } }, "examples": { "listed": { "summary": "Listed organizations", "value": { "success": true, "statusCode": 200, "message": "Organizations listed.", "data": [ { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "validationFailed": { "summary": "Invalid list query", "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "requestId": "4bf92f3577b34da6a3ce929d0e0e4736" } } } } } } } } } }, "/organizations/{organizationId}": { "post": { "operationId": "createOrganization", "summary": "Create an organization", "tags": [ "Organizations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" }, "example": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name", "rootUri", "config" ], "properties": { "slug": { "type": "string", "description": "Stable organization slug." }, "name": { "type": "string", "description": "Human-readable organization name." }, "status": { "type": "string", "enum": [ "onboarding", "active", "paused" ] }, "onboardedAt": { "type": "string", "format": "date-time", "nullable": true }, "rootUri": { "type": "string", "description": "Root URI for organization memory." }, "authorizationEpoch": { "type": "integer", "example": 1 }, "config": { "type": "object", "required": [ "timezone", "departments", "limits", "storageRootUri" ], "properties": { "timezone": { "type": "string", "description": "IANA timezone used by the organization." }, "departments": { "type": "object", "required": [ "growth", "engineering", "support" ], "properties": { "growth": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "engineering": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "support": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } } } }, "limits": { "type": "object", "required": [ "maxConcurrentRuns", "maxDailyActions", "maxTaskDepth", "maxPlanOperations", "maxInitiativeDescendants" ], "properties": { "maxConcurrentRuns": { "type": "integer", "example": 3 }, "maxDailyActions": { "type": "integer", "example": 100, "description": "Organization-local daily review threshold. Reaching it opens one non-blocking notification; task action budgets remain the hard limit." }, "maxTaskDepth": { "type": "integer", "example": 4 }, "maxPlanOperations": { "type": "integer", "example": 25, "description": "Maximum create and reopen operations accepted in one plan." }, "maxInitiativeDescendants": { "type": "integer", "example": 100, "description": "Maximum durable descendants allowed under one initiative." } } }, "storageRootUri": { "type": "string", "description": "Root URI for organization storage." } } }, "constraints": { "type": "object", "required": [ "allowedIntegrations", "blockedDomains", "approvalRequiredForRisk" ], "properties": { "allowedIntegrations": { "type": "array", "items": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "description": "Integration provider key." }, "externalId": { "type": "string", "description": "Provider-owned identifier." }, "uri": { "type": "string", "description": "Provider resource URI." } } } }, "blockedDomains": { "type": "array", "items": { "type": "string" } }, "approvalRequiredForRisk": { "type": "array", "items": { "type": "string", "enum": [ "low", "reversible", "external", "high" ] } } } } }, "example": { "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] } } }, "examples": { "organization": { "summary": "Create Acme", "value": { "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] } } } } } } }, "responses": { "201": { "description": "Organization created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "id", "slug", "name", "status", "rootUri", "authorizationEpoch", "config", "constraints", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Stable organization slug." }, "name": { "type": "string", "description": "Human-readable organization name." }, "status": { "type": "string", "enum": [ "onboarding", "active", "paused" ] }, "onboardedAt": { "type": "string", "format": "date-time", "nullable": true }, "rootUri": { "type": "string", "description": "Root URI for organization memory." }, "authorizationEpoch": { "type": "integer", "example": 1 }, "config": { "type": "object", "required": [ "timezone", "departments", "limits", "storageRootUri" ], "properties": { "timezone": { "type": "string", "description": "IANA timezone used by the organization." }, "departments": { "type": "object", "required": [ "growth", "engineering", "support" ], "properties": { "growth": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "engineering": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "support": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } } } }, "limits": { "type": "object", "required": [ "maxConcurrentRuns", "maxDailyActions", "maxTaskDepth", "maxPlanOperations", "maxInitiativeDescendants" ], "properties": { "maxConcurrentRuns": { "type": "integer", "example": 3 }, "maxDailyActions": { "type": "integer", "example": 100, "description": "Organization-local daily review threshold. Reaching it opens one non-blocking notification; task action budgets remain the hard limit." }, "maxTaskDepth": { "type": "integer", "example": 4 }, "maxPlanOperations": { "type": "integer", "example": 25, "description": "Maximum create and reopen operations accepted in one plan." }, "maxInitiativeDescendants": { "type": "integer", "example": 100, "description": "Maximum durable descendants allowed under one initiative." } } }, "storageRootUri": { "type": "string", "description": "Root URI for organization storage." } } }, "constraints": { "type": "object", "required": [ "allowedIntegrations", "blockedDomains", "approvalRequiredForRisk" ], "properties": { "allowedIntegrations": { "type": "array", "items": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "description": "Integration provider key." }, "externalId": { "type": "string", "description": "Provider-owned identifier." }, "uri": { "type": "string", "description": "Provider resource URI." } } } }, "blockedDomains": { "type": "array", "items": { "type": "string" } }, "approvalRequiredForRisk": { "type": "array", "items": { "type": "string", "enum": [ "low", "reversible", "external", "high" ] } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "example": { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "created": { "summary": "Created organization", "value": { "success": true, "statusCode": 201, "message": "Organization created.", "data": { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "validationFailed": { "summary": "Invalid organization payload", "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "requestId": "4bf92f3577b34da6a3ce929d0e0e4736" } } } } } } } } }, "get": { "operationId": "getOrganization", "summary": "Get an organization", "tags": [ "Organizations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" }, "example": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1" } ], "responses": { "200": { "description": "Organization found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "id", "slug", "name", "status", "rootUri", "authorizationEpoch", "config", "constraints", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Stable organization slug." }, "name": { "type": "string", "description": "Human-readable organization name." }, "status": { "type": "string", "enum": [ "onboarding", "active", "paused" ] }, "onboardedAt": { "type": "string", "format": "date-time", "nullable": true }, "rootUri": { "type": "string", "description": "Root URI for organization memory." }, "authorizationEpoch": { "type": "integer", "example": 1 }, "config": { "type": "object", "required": [ "timezone", "departments", "limits", "storageRootUri" ], "properties": { "timezone": { "type": "string", "description": "IANA timezone used by the organization." }, "departments": { "type": "object", "required": [ "growth", "engineering", "support" ], "properties": { "growth": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "engineering": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "support": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } } } }, "limits": { "type": "object", "required": [ "maxConcurrentRuns", "maxDailyActions", "maxTaskDepth", "maxPlanOperations", "maxInitiativeDescendants" ], "properties": { "maxConcurrentRuns": { "type": "integer", "example": 3 }, "maxDailyActions": { "type": "integer", "example": 100, "description": "Organization-local daily review threshold. Reaching it opens one non-blocking notification; task action budgets remain the hard limit." }, "maxTaskDepth": { "type": "integer", "example": 4 }, "maxPlanOperations": { "type": "integer", "example": 25, "description": "Maximum create and reopen operations accepted in one plan." }, "maxInitiativeDescendants": { "type": "integer", "example": 100, "description": "Maximum durable descendants allowed under one initiative." } } }, "storageRootUri": { "type": "string", "description": "Root URI for organization storage." } } }, "constraints": { "type": "object", "required": [ "allowedIntegrations", "blockedDomains", "approvalRequiredForRisk" ], "properties": { "allowedIntegrations": { "type": "array", "items": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "description": "Integration provider key." }, "externalId": { "type": "string", "description": "Provider-owned identifier." }, "uri": { "type": "string", "description": "Provider resource URI." } } } }, "blockedDomains": { "type": "array", "items": { "type": "string" } }, "approvalRequiredForRisk": { "type": "array", "items": { "type": "string", "enum": [ "low", "reversible", "external", "high" ] } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "example": { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "found": { "summary": "Found organization", "value": { "success": true, "statusCode": 200, "message": "Organization found.", "data": { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "validationFailed": { "summary": "Invalid organization id", "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "requestId": "4bf92f3577b34da6a3ce929d0e0e4736" } } } } } } }, "404": { "description": "Organization not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "notFound": { "summary": "Missing organization", "value": { "success": false, "statusCode": 404, "message": "Organization not found.", "error": { "code": "organization_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } }, "patch": { "operationId": "updateOrganization", "summary": "Update an organization", "tags": [ "Organizations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" }, "example": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "slug": { "type": "string", "description": "Stable organization slug." }, "name": { "type": "string", "description": "Human-readable organization name." }, "status": { "type": "string", "enum": [ "onboarding", "active", "paused" ] }, "onboardedAt": { "type": "string", "format": "date-time", "nullable": true }, "rootUri": { "type": "string", "description": "Root URI for organization memory." }, "authorizationEpoch": { "type": "integer", "example": 1 }, "config": { "type": "object", "required": [ "timezone", "departments", "limits", "storageRootUri" ], "properties": { "timezone": { "type": "string", "description": "IANA timezone used by the organization." }, "departments": { "type": "object", "required": [ "growth", "engineering", "support" ], "properties": { "growth": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "engineering": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "support": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } } } }, "limits": { "type": "object", "required": [ "maxConcurrentRuns", "maxDailyActions", "maxTaskDepth", "maxPlanOperations", "maxInitiativeDescendants" ], "properties": { "maxConcurrentRuns": { "type": "integer", "example": 3 }, "maxDailyActions": { "type": "integer", "example": 100, "description": "Organization-local daily review threshold. Reaching it opens one non-blocking notification; task action budgets remain the hard limit." }, "maxTaskDepth": { "type": "integer", "example": 4 }, "maxPlanOperations": { "type": "integer", "example": 25, "description": "Maximum create and reopen operations accepted in one plan." }, "maxInitiativeDescendants": { "type": "integer", "example": 100, "description": "Maximum durable descendants allowed under one initiative." } } }, "storageRootUri": { "type": "string", "description": "Root URI for organization storage." } } }, "constraints": { "type": "object", "required": [ "allowedIntegrations", "blockedDomains", "approvalRequiredForRisk" ], "properties": { "allowedIntegrations": { "type": "array", "items": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "description": "Integration provider key." }, "externalId": { "type": "string", "description": "Provider-owned identifier." }, "uri": { "type": "string", "description": "Provider resource URI." } } } }, "blockedDomains": { "type": "array", "items": { "type": "string" } }, "approvalRequiredForRisk": { "type": "array", "items": { "type": "string", "enum": [ "low", "reversible", "external", "high" ] } } } } }, "example": { "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] } } }, "examples": { "rename": { "summary": "Rename organization", "value": { "name": "Acme Global" } } } } } }, "responses": { "200": { "description": "Organization updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "id", "slug", "name", "status", "rootUri", "authorizationEpoch", "config", "constraints", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Stable organization slug." }, "name": { "type": "string", "description": "Human-readable organization name." }, "status": { "type": "string", "enum": [ "onboarding", "active", "paused" ] }, "onboardedAt": { "type": "string", "format": "date-time", "nullable": true }, "rootUri": { "type": "string", "description": "Root URI for organization memory." }, "authorizationEpoch": { "type": "integer", "example": 1 }, "config": { "type": "object", "required": [ "timezone", "departments", "limits", "storageRootUri" ], "properties": { "timezone": { "type": "string", "description": "IANA timezone used by the organization." }, "departments": { "type": "object", "required": [ "growth", "engineering", "support" ], "properties": { "growth": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "engineering": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "support": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } } } }, "limits": { "type": "object", "required": [ "maxConcurrentRuns", "maxDailyActions", "maxTaskDepth", "maxPlanOperations", "maxInitiativeDescendants" ], "properties": { "maxConcurrentRuns": { "type": "integer", "example": 3 }, "maxDailyActions": { "type": "integer", "example": 100, "description": "Organization-local daily review threshold. Reaching it opens one non-blocking notification; task action budgets remain the hard limit." }, "maxTaskDepth": { "type": "integer", "example": 4 }, "maxPlanOperations": { "type": "integer", "example": 25, "description": "Maximum create and reopen operations accepted in one plan." }, "maxInitiativeDescendants": { "type": "integer", "example": 100, "description": "Maximum durable descendants allowed under one initiative." } } }, "storageRootUri": { "type": "string", "description": "Root URI for organization storage." } } }, "constraints": { "type": "object", "required": [ "allowedIntegrations", "blockedDomains", "approvalRequiredForRisk" ], "properties": { "allowedIntegrations": { "type": "array", "items": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "description": "Integration provider key." }, "externalId": { "type": "string", "description": "Provider-owned identifier." }, "uri": { "type": "string", "description": "Provider resource URI." } } } }, "blockedDomains": { "type": "array", "items": { "type": "string" } }, "approvalRequiredForRisk": { "type": "array", "items": { "type": "string", "enum": [ "low", "reversible", "external", "high" ] } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "example": { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "updated": { "summary": "Updated organization", "value": { "success": true, "statusCode": 200, "message": "Organization updated.", "data": { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme Global", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "validationFailed": { "summary": "Invalid update payload", "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "requestId": "4bf92f3577b34da6a3ce929d0e0e4736" } } } } } } }, "404": { "description": "Organization not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "notFound": { "summary": "Missing organization", "value": { "success": false, "statusCode": 404, "message": "Organization not found.", "error": { "code": "organization_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } }, "delete": { "operationId": "deleteOrganization", "summary": "Delete an organization", "tags": [ "Organizations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" }, "example": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1" } ], "responses": { "200": { "description": "Organization deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "id", "slug", "name", "status", "rootUri", "authorizationEpoch", "config", "constraints", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "Stable organization slug." }, "name": { "type": "string", "description": "Human-readable organization name." }, "status": { "type": "string", "enum": [ "onboarding", "active", "paused" ] }, "onboardedAt": { "type": "string", "format": "date-time", "nullable": true }, "rootUri": { "type": "string", "description": "Root URI for organization memory." }, "authorizationEpoch": { "type": "integer", "example": 1 }, "config": { "type": "object", "required": [ "timezone", "departments", "limits", "storageRootUri" ], "properties": { "timezone": { "type": "string", "description": "IANA timezone used by the organization." }, "departments": { "type": "object", "required": [ "growth", "engineering", "support" ], "properties": { "growth": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "engineering": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } }, "support": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "defaultAgentProfileKey": { "type": "string", "description": "Default agent profile key for this department." }, "workspaceUri": { "type": "string", "description": "Workspace URI for this department." } } } } }, "limits": { "type": "object", "required": [ "maxConcurrentRuns", "maxDailyActions", "maxTaskDepth", "maxPlanOperations", "maxInitiativeDescendants" ], "properties": { "maxConcurrentRuns": { "type": "integer", "example": 3 }, "maxDailyActions": { "type": "integer", "example": 100, "description": "Organization-local daily review threshold. Reaching it opens one non-blocking notification; task action budgets remain the hard limit." }, "maxTaskDepth": { "type": "integer", "example": 4 }, "maxPlanOperations": { "type": "integer", "example": 25, "description": "Maximum create and reopen operations accepted in one plan." }, "maxInitiativeDescendants": { "type": "integer", "example": 100, "description": "Maximum durable descendants allowed under one initiative." } } }, "storageRootUri": { "type": "string", "description": "Root URI for organization storage." } } }, "constraints": { "type": "object", "required": [ "allowedIntegrations", "blockedDomains", "approvalRequiredForRisk" ], "properties": { "allowedIntegrations": { "type": "array", "items": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "description": "Integration provider key." }, "externalId": { "type": "string", "description": "Provider-owned identifier." }, "uri": { "type": "string", "description": "Provider resource URI." } } } }, "blockedDomains": { "type": "array", "items": { "type": "string" } }, "approvalRequiredForRisk": { "type": "array", "items": { "type": "string", "enum": [ "low", "reversible", "external", "high" ] } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "example": { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "deleted": { "summary": "Deleted organization", "value": { "success": true, "statusCode": 200, "message": "Organization deleted.", "data": { "id": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "slug": "acme", "name": "Acme", "status": "active", "onboardedAt": "2026-01-01T00:00:00.000Z", "rootUri": "memory://organizations/acme", "authorizationEpoch": 1, "config": { "timezone": "UTC", "departments": { "growth": { "enabled": true }, "engineering": { "enabled": true }, "support": { "enabled": true } }, "limits": { "maxConcurrentRuns": 3, "maxDailyActions": 100, "maxTaskDepth": 4, "maxPlanOperations": 25, "maxInitiativeDescendants": 100 }, "storageRootUri": "memory://organizations/acme" }, "constraints": { "allowedIntegrations": [], "blockedDomains": [], "approvalRequiredForRisk": [ "external", "high" ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "validationFailed": { "summary": "Invalid organization id", "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "requestId": "4bf92f3577b34da6a3ce929d0e0e4736" } } } } } } }, "404": { "description": "Organization not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "meta": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "traceId": { "type": "string" }, "requestId": { "type": "string" } } } } }, "examples": { "notFound": { "summary": "Missing organization", "value": { "success": false, "statusCode": 404, "message": "Organization not found.", "error": { "code": "organization_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/actions": { "get": { "operationId": "listActions", "summary": "List organization actions", "tags": [ "Actions" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "id", "tool", "operation", "status", "risk", "availableAt", "createdAt", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "runId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "agentProfileId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "proposed", "waiting_approval", "approved", "executing", "succeeded", "failed", "unknown", "rejected", "cancelled" ] } }, { "name": "risk", "in": "query", "schema": { "type": "string", "enum": [ "low", "reversible", "external", "high" ] } } ], "responses": { "200": { "description": "Organization-scoped action response." } } } }, "/organizations/{organizationId}/actions/{id}": { "get": { "operationId": "getAction", "summary": "Get an organization action", "tags": [ "Actions" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization-scoped action response." } } } }, "/organizations/{organizationId}/actions/{id}/approve": { "post": { "operationId": "approveAction", "summary": "Approve a waiting consequential action", "tags": [ "Actions" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization-scoped action response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 2000 } } } } } } } }, "/organizations/{organizationId}/actions/{id}/reject": { "post": { "operationId": "rejectAction", "summary": "Reject a waiting consequential action", "tags": [ "Actions" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization-scoped action response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 2000 } } } } } } } }, "/organizations/{organizationId}/actions/{id}/reconcile": { "post": { "operationId": "reconcileAction", "summary": "Reconcile an action with an unknown provider outcome", "tags": [ "Actions" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization-scoped action response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "outcome", "note" ], "properties": { "outcome": { "type": "string", "enum": [ "succeeded", "failed" ] }, "note": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } } } } }, "/organizations/{organizationId}/agent-profiles": { "get": { "operationId": "listAgentProfiles", "summary": "List agent profiles", "tags": [ "Agent Profiles" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "id", "key", "name", "kind", "status", "createdAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "key", "in": "query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "operator", "chat", "department" ] } }, { "name": "department", "in": "query", "schema": { "type": "string", "enum": [ "growth", "engineering", "support" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "enabled", "disabled" ] } } ], "responses": { "200": { "description": "Agent profiles listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "example": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Agent profiles listed.", "data": [ { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } }, "post": { "operationId": "createAgentProfile", "summary": "Create agent profile", "tags": [ "Agent Profiles" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "kind", "rootUri", "config" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "operator", "chat", "department" ] }, "department": { "type": "string", "enum": [ "growth", "engineering", "support" ], "nullable": true }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "rootUri": { "type": "string" }, "instructionsUri": { "type": "string" }, "config": { "type": "object", "additionalProperties": true } }, "example": { "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "examples": { "example": { "value": { "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } } } } }, "responses": { "201": { "description": "Agent profile created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Agent profile created.", "data": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/agent-profiles/{id}": { "get": { "operationId": "getAgentProfile", "summary": "Get agent profile", "tags": [ "Agent Profiles" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent profile found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Agent profile found.", "data": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Agent profile not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Agent profile not found.", "error": { "code": "agent_profile_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } }, "patch": { "operationId": "updateAgentProfile", "summary": "Update agent profile", "tags": [ "Agent Profiles" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "operator", "chat", "department" ] }, "department": { "type": "string", "enum": [ "growth", "engineering", "support" ], "nullable": true }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "rootUri": { "type": "string" }, "instructionsUri": { "type": "string" }, "config": { "type": "object", "additionalProperties": true } }, "example": { "name": "Growth Team" } }, "examples": { "example": { "value": { "name": "Growth Team" } } } } } }, "responses": { "200": { "description": "Agent profile updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Agent profile updated.", "data": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Agent profile not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Agent profile not found.", "error": { "code": "agent_profile_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } }, "delete": { "operationId": "deleteAgentProfile", "summary": "Delete agent profile", "tags": [ "Agent Profiles" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent profile deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Agent profile deleted.", "data": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Agent profile not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Agent profile not found.", "error": { "code": "agent_profile_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/agent-profile-templates": { "get": { "operationId": "listAgentProfileTemplates", "summary": "List current agent profile templates", "tags": [ "Agent Profiles" ], "responses": { "200": { "description": "Agent profile templates found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "revision", "catalog" ], "properties": { "revision": { "type": "string", "example": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "catalog": { "type": "object", "required": [ "version", "commonSkillKeys", "commonMcpServerKeys", "profiles" ], "properties": { "version": { "type": "integer", "example": 1 }, "commonSkillKeys": { "type": "array", "items": { "type": "string" } }, "commonMcpServerKeys": { "type": "array", "items": { "type": "string" } }, "profiles": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "summary", "kind", "skillKeys", "mcpServerKeys", "config" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "kind": { "type": "string", "enum": [ "operator", "chat", "department" ] }, "department": { "type": "string", "enum": [ "growth", "engineering", "support" ] }, "skillKeys": { "type": "array", "items": { "type": "string" } }, "mcpServerKeys": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "additionalProperties": true } }, "example": { "key": "growth", "name": "Growth", "summary": "Owns acquisition, activation, retention, and growth experimentation work.", "kind": "department", "department": "growth", "skillKeys": [ "growth-operations" ], "mcpServerKeys": [], "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 1, "toolPolicyKeys": [] } } } } } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Agent profile templates found.", "data": { "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "catalog": { "version": 1, "commonSkillKeys": [ "operational-durability" ], "commonMcpServerKeys": [], "profiles": [ { "key": "growth", "name": "Growth", "summary": "Owns acquisition, activation, retention, and growth experimentation work.", "kind": "department", "department": "growth", "skillKeys": [ "growth-operations" ], "mcpServerKeys": [], "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 1, "toolPolicyKeys": [] } } ] } }, "meta": { "timestamp": "2026-07-14T10:00:00.000Z" } } } } } } }, "503": { "description": "No catalog is published.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 503, "message": "No agent-pack catalog has been published.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T10:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/agent-profiles/provision": { "post": { "operationId": "provisionAgentProfiles", "summary": "Provision organization agent profiles", "description": "Pins operator, chat, and selected department profiles to an immutable catalog revision.", "tags": [ "Agent Profiles" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "departments" ], "properties": { "departments": { "type": "array", "items": { "type": "string", "enum": [ "growth", "engineering", "support" ] } }, "catalogRevision": { "type": "string", "description": "Optional immutable catalog revision. The current revision is used when omitted." } }, "example": { "departments": [ "growth", "support" ], "catalogRevision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } }, "responses": { "200": { "description": "Agent profiles updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "revision", "profiles", "disabledProfileIds" ], "properties": { "revision": { "type": "string", "example": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "profiles": { "type": "array", "items": { "type": "object", "additionalProperties": true, "example": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "disabledProfileIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Agent profiles updated.", "data": { "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "profiles": [ { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "key": "growth", "name": "Growth", "kind": "department", "department": "growth", "status": "enabled", "rootUri": "memory://organizations/acme/agents/growth", "instructionsUri": "memory://organizations/acme/agents/growth/instructions.md", "config": { "defaultRunMode": "execute", "maxConcurrentRuns": 2, "toolPolicyKeys": [ "growth-default" ], "memoryRootUri": "memory://organizations/acme/agents/growth", "skillKeys": [ "operational-durability", "growth-operations" ], "mcpServerKeys": [], "catalogSource": { "templateKey": "growth", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "disabledProfileIds": [] }, "meta": { "timestamp": "2026-07-14T10:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Organization or catalog revision not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Organization not found.", "error": { "code": "request_failed" }, "meta": { "timestamp": "2026-07-14T10:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/chats": { "get": { "operationId": "listChats", "summary": "List chats", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque cursor returned by the previous page." } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "id", "title", "status", "lastMessageAt", "createdAt", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "archived" ] } }, { "name": "isOnboardingChat", "in": "query", "schema": { "type": "boolean" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across chat titles and visible message content.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chats listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "example": { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false } } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Chats listed.", "data": [ { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } }, "post": { "operationId": "createChat", "summary": "Create chat", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "User-visible title for a general chat." } }, "example": { "title": "Customer Escalation" } }, "examples": { "example": { "value": { "title": "Customer Escalation" } } } } } }, "responses": { "201": { "description": "Chat created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Chat created.", "data": { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/chats/{id}": { "get": { "operationId": "getChat", "summary": "Get chat", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Chat found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Chat found.", "data": { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Chat not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Chat not found.", "error": { "code": "chat_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } }, "patch": { "operationId": "updateChat", "summary": "Update chat", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "User-visible title for a general chat." }, "status": { "type": "string", "enum": [ "open", "archived" ], "description": "Open restores a chat; archived archives it using server time." } }, "example": { "title": "Customer Escalation" } }, "examples": { "example": { "value": { "title": "Customer Escalation" } } } } } }, "responses": { "200": { "description": "Chat updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Chat updated.", "data": { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Chat not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Chat not found.", "error": { "code": "chat_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "409": { "description": "Chat update conflicts with protected state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Wait for the active assistant response to finish before archiving this chat.", "error": { "code": "chat_response_active" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } }, "delete": { "operationId": "deleteChat", "summary": "Delete chat", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Chat deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Chat deleted.", "data": { "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "title": "Customer Escalation", "status": "open", "summary": null, "harnessSessionId": null, "settings": { "pinnedTaskIds": [] }, "lastMessageAt": "2026-01-01T00:00:00.000Z", "archivedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "isOnboardingChat": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Chat not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Chat not found.", "error": { "code": "chat_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "409": { "description": "Onboarding chat cannot be deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "The organization onboarding chat cannot be changed.", "error": { "code": "onboarding_chat_immutable" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/chats/{chatId}/events": { "get": { "operationId": "streamChatEvents", "summary": "Stream chat events", "description": "Starts with the latest persisted assistant snapshot, then streams revisioned message updates.", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "chatId", "in": "path", "required": true, "description": "Chat identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Last-Event-ID", "in": "header", "description": "Last processed event in assistantMessageId:revision format.", "schema": { "type": "string" }, "example": "d4ad2b33-d18c-45c2-965d-22a883af9d89:4" } ], "responses": { "200": { "description": "Server-sent chat event stream.", "content": { "text/event-stream": { "schema": { "type": "string" }, "examples": { "snapshot": { "value": "id: d4ad2b33-d18c-45c2-965d-22a883af9d89:4\nevent: chat.snapshot\ndata: {\"type\":\"chat.snapshot\"}\n\n" } } } } } } } }, "/organizations/{organizationId}/chats/{chatId}/messages/{messageId}/cancel": { "post": { "operationId": "cancelChatMessage", "summary": "Cancel assistant response", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "chatId", "in": "path", "required": true, "description": "Chat identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "messageId", "in": "path", "required": true, "description": "Assistant message identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Message cancellation requested.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Message cancellation requested.", "data": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "assistant", "status": "cancelling", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Assistant message not found.", "error": { "code": "message_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "409": { "description": "Message cannot be cancelled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Assistant message cannot be cancelled from its current state.", "error": { "code": "message_not_cancellable" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/chats/{chatId}/attachments/{attachmentId}": { "put": { "operationId": "putChatAttachment", "summary": "Upload a chat attachment", "description": "Stores up to 50 MB of supported reference content under a client-generated, chat-scoped identifier.", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "chatId", "in": "path", "required": true, "description": "Chat identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "description": "Client-generated attachment identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fileName", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "mediaType", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "201": { "description": "Chat attachment stored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Chat attachment stored.", "data": { "version": 1, "id": "31d22752-e70d-42ce-a28a-39dc87dc8fc8", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "fileName": "project-brief.md", "mediaType": "text/markdown", "sizeBytes": 2048, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "createdAt": "2026-07-15T09:00:00.000Z", "uri": "oblive://organizations/7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1/chats/0ce65ee0-dcd9-46c2-90a4-243f5d54dc66/attachments/31d22752-e70d-42ce-a28a-39dc87dc8fc8" }, "meta": { "timestamp": "2026-07-15T09:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "409": { "description": "Attachment is not allowed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Attachments can only be added to open, non-onboarding chats.", "error": { "code": "attachment_not_allowed" }, "meta": { "timestamp": "2026-07-15T09:00:00.000Z" } } } } } } }, "413": { "description": "Attachment is too large.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 413, "message": "Attachments cannot exceed 50 MB.", "error": { "code": "attachment_invalid" }, "meta": { "timestamp": "2026-07-15T09:00:00.000Z" } } } } } } }, "415": { "description": "Attachment type is unsupported.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 415, "message": "Attachment type is unsupported.", "error": { "code": "attachment_invalid" }, "meta": { "timestamp": "2026-07-15T09:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/chats/{chatId}/attachments/{attachmentId}/content": { "get": { "operationId": "getChatAttachmentContent", "summary": "Read chat attachment bytes", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "chatId", "in": "path", "required": true, "description": "Chat identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "description": "Client-generated attachment identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "disposition", "in": "query", "schema": { "type": "string", "enum": [ "inline", "attachment" ] } }, { "name": "Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original attachment bytes. Supports HEAD and one byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Original attachment bytes. Supports HEAD and one byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Chat attachment not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Chat attachment not found.", "error": { "code": "attachment_not_found" }, "meta": { "timestamp": "2026-07-15T09:00:00.000Z" } } } } } } }, "416": { "description": "Range is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 416, "message": "Requested byte range is not satisfiable.", "error": { "code": "range_not_satisfiable" }, "meta": { "timestamp": "2026-07-15T09:00:00.000Z" } } } } } } } } }, "head": { "operationId": "headChatAttachmentContent", "summary": "Read chat attachment metadata", "tags": [ "Chats" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "chatId", "in": "path", "required": true, "description": "Chat identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "description": "Client-generated attachment identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "disposition", "in": "query", "schema": { "type": "string", "enum": [ "inline", "attachment" ] } }, { "name": "Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original attachment bytes. Supports HEAD and one byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Original attachment bytes. Supports HEAD and one byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Chat attachment not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Chat attachment not found.", "error": { "code": "attachment_not_found" }, "meta": { "timestamp": "2026-07-15T09:00:00.000Z" } } } } } } }, "416": { "description": "Range is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 416, "message": "Requested byte range is not satisfiable.", "error": { "code": "range_not_satisfiable" }, "meta": { "timestamp": "2026-07-15T09:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/context/files": { "get": { "operationId": "listOrganizationContextFiles", "summary": "List visible context files", "tags": [ "Organization Context" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 100 } } ], "responses": { "200": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/organizations/{organizationId}/context/files/content": { "get": { "operationId": "getOrganizationContextFileContent", "summary": "Read organization context file bytes", "tags": [ "Organization Context" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "disposition", "in": "query", "schema": { "type": "string", "enum": [ "inline", "attachment" ] } }, { "name": "Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original context bytes. Supports HEAD and a single byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Original context bytes. Supports HEAD and a single byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "416": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "head": { "operationId": "headOrganizationContextFileContent", "summary": "Read organization context file metadata", "tags": [ "Organization Context" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "disposition", "in": "query", "schema": { "type": "string", "enum": [ "inline", "attachment" ] } }, { "name": "Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original context bytes. Supports HEAD and a single byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Original context bytes. Supports HEAD and a single byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "416": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/organizations/{organizationId}/context/sources": { "get": { "operationId": "listOrganizationContextSources", "summary": "List retained onboarding sources", "tags": [ "Organization Context" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 100 } } ], "responses": { "200": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/organizations/{organizationId}/context/sources/{sourceId}/content": { "get": { "operationId": "getOrganizationContextSourceContent", "summary": "Read retained onboarding source bytes", "tags": [ "Organization Context" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "disposition", "in": "query", "schema": { "type": "string", "enum": [ "inline", "attachment" ] } }, { "name": "Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original context bytes. Supports HEAD and a single byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Original context bytes. Supports HEAD and a single byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "416": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "head": { "operationId": "headOrganizationContextSourceContent", "summary": "Read retained source metadata", "tags": [ "Organization Context" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "disposition", "in": "query", "schema": { "type": "string", "enum": [ "inline", "attachment" ] } }, { "name": "Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original context bytes. Supports HEAD and a single byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Original context bytes. Supports HEAD and a single byte range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "416": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/organizations/{organizationId}/context/health": { "get": { "operationId": "getOrganizationContextHealth", "summary": "Get current or recent context health", "description": "Returns one aggregate Context Health product with version-3 general and integration findings, full-audit freshness, integration-reconciliation freshness, and assessment-labeled immutable revisions. Version-2 history is normalized on read without rewriting stored bytes.", "tags": [ "Organization Context" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Typed JSON response envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/organizations/{organizationId}/durability": { "get": { "operationId": "listDurability", "summary": "List durability rows", "tags": [ "Durability" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "description": "Cursor formatted as namespace:key.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "namespace", "key", "kind", "version", "expiresAt", "createdAt", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "namespace", "in": "query", "schema": { "type": "string", "enum": [ "chat", "task", "department", "system", "connector", "run" ] } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "chat_summary", "task_checkpoint", "run_checkpoint", "connector_cursor", "learning_watermark", "context_health", "integration_context_reconciliation", "run_outcome", "profile_memory" ] } }, { "name": "sourceRunId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "expiresBefore", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Durability rows listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "example": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "namespace": "task", "key": "task:b12e12e7:checkpoint", "kind": "task_checkpoint", "version": 1, "payload": { "kind": "task_checkpoint", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "taskVersion": 1, "summary": "Initial plan drafted.", "artifactUris": [ "artifact://tasks/b12e12e7/plan.md" ] }, "sourceRunId": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "expiresAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Durability rows listed.", "data": [ { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "namespace": "task", "key": "task:b12e12e7:checkpoint", "kind": "task_checkpoint", "version": 1, "payload": { "kind": "task_checkpoint", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "taskVersion": 1, "summary": "Initial plan drafted.", "artifactUris": [ "artifact://tasks/b12e12e7/plan.md" ] }, "sourceRunId": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "expiresAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/durability/{namespace}/{key}": { "get": { "operationId": "getDurability", "summary": "Get durability row", "tags": [ "Durability" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "namespace", "in": "path", "required": true, "description": "Durability namespace.", "schema": { "type": "string", "enum": [ "chat", "task", "department", "system", "connector", "run" ] } }, { "name": "key", "in": "path", "required": true, "description": "Durability key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Durability row found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "namespace": "task", "key": "task:b12e12e7:checkpoint", "kind": "task_checkpoint", "version": 1, "payload": { "kind": "task_checkpoint", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "taskVersion": 1, "summary": "Initial plan drafted.", "artifactUris": [ "artifact://tasks/b12e12e7/plan.md" ] }, "sourceRunId": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "expiresAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Durability row found.", "data": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "namespace": "task", "key": "task:b12e12e7:checkpoint", "kind": "task_checkpoint", "version": 1, "payload": { "kind": "task_checkpoint", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "taskVersion": 1, "summary": "Initial plan drafted.", "artifactUris": [ "artifact://tasks/b12e12e7/plan.md" ] }, "sourceRunId": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "expiresAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Durability row not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Durability row not found.", "error": { "code": "durability_row_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/human-inbox": { "get": { "operationId": "listHumanInboxItems", "summary": "List human inbox items", "tags": [ "Human Inbox" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Human inbox items listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Human inbox items listed.", "data": [] } } } } } } } } }, "/organizations/{organizationId}/human-inbox/{inboxItemId}": { "get": { "operationId": "getHumanInboxItem", "summary": "Get human inbox item", "tags": [ "Human Inbox" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "inboxItemId", "in": "path", "required": true, "description": "Human inbox item identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Human inbox item found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Human inbox item found.", "data": { "id": "fa37c769-25f9-4bf7-9acd-98f8464d87db", "status": "open" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "404": { "description": "Human inbox item not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Human inbox item was not found.", "error": { "code": "human_inbox_item_not_found" } } } } } } }, "409": { "description": "Human inbox item state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Human inbox item is no longer open.", "error": { "code": "human_inbox_item_not_open" } } } } } } } } } }, "/organizations/{organizationId}/human-inbox/{inboxItemId}/respond": { "post": { "operationId": "respondToHumanInboxItem", "summary": "Answer human inbox question", "tags": [ "Human Inbox" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "inboxItemId", "in": "path", "required": true, "description": "Human inbox item identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "response" ], "properties": { "response": { "type": "string" } } }, "examples": { "answer": { "value": { "response": "Use the EU tax region." } } } } } }, "responses": { "200": { "description": "Human inbox item found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Human inbox item found.", "data": { "id": "fa37c769-25f9-4bf7-9acd-98f8464d87db", "status": "open" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "404": { "description": "Human inbox item not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Human inbox item was not found.", "error": { "code": "human_inbox_item_not_found" } } } } } } }, "409": { "description": "Human inbox item state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Human inbox item is no longer open.", "error": { "code": "human_inbox_item_not_open" } } } } } } } } } }, "/organizations/{organizationId}/human-inbox/{inboxItemId}/acknowledge": { "post": { "operationId": "acknowledgeHumanInboxItem", "summary": "Acknowledge human inbox notification", "tags": [ "Human Inbox" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "inboxItemId", "in": "path", "required": true, "description": "Human inbox item identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Human inbox item found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Human inbox item found.", "data": { "id": "fa37c769-25f9-4bf7-9acd-98f8464d87db", "status": "open" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "404": { "description": "Human inbox item not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Human inbox item was not found.", "error": { "code": "human_inbox_item_not_found" } } } } } } }, "409": { "description": "Human inbox item state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Human inbox item is no longer open.", "error": { "code": "human_inbox_item_not_open" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/status": { "get": { "operationId": "getAgentStatus", "summary": "Get agent organization status", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/context/promotions": { "post": { "operationId": "promoteAgentContext", "summary": "Promote an owner-reviewed chat proposal into Context", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "request": { "value": {} } } } } }, "responses": { "201": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/tasks/{taskRef}/context-revisions/promote": { "post": { "operationId": "promoteAgentContextRevision", "summary": "Promote a human-approved structured Context revision", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task UUID or identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "request": { "value": {} } } } } }, "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/tasks": { "get": { "operationId": "listAgentTasks", "summary": "List tasks for agents", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } }, "post": { "operationId": "createAgentTask", "summary": "Create task as an agent", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "request": { "value": {} } } } } }, "responses": { "201": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/tasks/{taskRef}": { "get": { "operationId": "getAgentTask", "summary": "Get task by reference", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task UUID or identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } }, "patch": { "operationId": "updateAgentTask", "summary": "Safely update task planning fields", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task UUID or identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "request": { "value": {} } } } } }, "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/tasks/{taskRef}/dependencies": { "get": { "operationId": "listAgentTaskDependencies", "summary": "List task prerequisites and dependents", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task UUID or identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } }, "post": { "operationId": "createAgentTaskDependency", "summary": "Add a planning dependency", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task UUID or identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "request": { "value": {} } } } } }, "responses": { "201": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/tasks/{taskRef}/cancel": { "post": { "operationId": "cancelAgentTask", "summary": "Cancel task subtree and active executions", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task UUID or identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "request": { "value": {} } } } } }, "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/tasks/{taskRef}/human-inbox": { "post": { "operationId": "createAgentHumanInboxItem", "summary": "Ask or notify a human", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task UUID or identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "request": { "value": {} } } } } }, "responses": { "201": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/tasks/{taskRef}/outcomes": { "post": { "operationId": "submitAgentTaskOutcome", "summary": "Stage a typed plan or outcome for the active task run", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task UUID or identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "request": { "value": {} } } } } }, "responses": { "201": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/schedules": { "get": { "operationId": "listAgentSchedules", "summary": "List schedules for agents", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } }, "post": { "operationId": "createAgentSchedule", "summary": "Create schedule as an agent", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "request": { "value": {} } } } } }, "responses": { "201": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 201, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/schedules/{scheduleRef}/pause": { "post": { "operationId": "pauseAgentSchedule", "summary": "Pause schedule", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "scheduleRef", "in": "path", "required": true, "description": "Schedule UUID or stable key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/schedules/{scheduleRef}/resume": { "post": { "operationId": "resumeAgentSchedule", "summary": "Resume schedule", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "scheduleRef", "in": "path", "required": true, "description": "Schedule UUID or stable key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/internal/agent/organizations/{organizationId}/schedules/{scheduleRef}": { "delete": { "operationId": "deleteAgentSchedule", "summary": "Delete schedule", "tags": [ "Internal Agent" ], "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "scheduleRef", "in": "path", "required": true, "description": "Schedule UUID or stable key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Control-plane operation completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Control-plane operation completed.", "data": {} } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token or execution capability.", "error": { "code": "agent_unauthorized" } } } } } } }, "404": { "description": "Control-plane entity not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Control-plane entity was not found.", "error": { "code": "not_found" } } } } } } }, "409": { "description": "Control-plane state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Control-plane state conflict.", "error": { "code": "state_conflict" } } } } } } } } } }, "/organizations/{organizationId}/chats/{chatId}/messages": { "get": { "operationId": "listChatMessages", "summary": "List chat messages", "tags": [ "Messages" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "chatId", "in": "path", "required": true, "description": "Chat identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque cursor returned by the previous page." } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "id", "chatId", "role", "status", "createdAt", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "role", "in": "query", "schema": { "type": "string", "enum": [ "user", "assistant", "system", "tool" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "cancelling", "complete", "failed", "cancelled" ] } } ], "responses": { "200": { "description": "Messages listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "example": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Messages listed.", "data": [ { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } }, "post": { "operationId": "sendChatMessage", "summary": "Send chat message", "description": "Persists the user message and its pending assistant response atomically.", "tags": [ "Messages" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "chatId", "in": "path", "required": true, "description": "Chat identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parts" ], "properties": { "author": { "type": "object", "additionalProperties": true }, "parts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "example": { "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "kind": "text", "text": "Create the onboarding plan." } ] } }, "examples": { "message": { "value": { "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "kind": "text", "text": "Create the onboarding plan." } ] } } } } } }, "responses": { "202": { "description": "Message accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "userMessage", "assistantMessage" ], "properties": { "userMessage": { "type": "object", "additionalProperties": true, "example": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "assistantMessage": { "type": "object", "additionalProperties": true, "example": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 202, "message": "Message accepted.", "data": { "userMessage": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "assistantMessage": { "id": "d4ad2b33-d18c-45c2-965d-22a883af9d89", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "role": "assistant", "status": "pending", "revision": 1, "author": null, "parts": [], "error": null, "completedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "409": { "description": "Chat is busy.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "This chat already has an active assistant response.", "error": { "code": "chat_turn_active" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/messages/{id}": { "get": { "operationId": "getMessage", "summary": "Get message", "tags": [ "Messages" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Message found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Message found.", "data": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Message not found.", "error": { "code": "message_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/internal/chat/messages/{assistantMessageId}/claim": { "post": { "operationId": "claimInternalChatMessage", "summary": "Claim pending assistant message", "tags": [ "Internal Chat" ], "security": [ { "agentServiceToken": [] } ], "parameters": [ { "name": "assistantMessageId", "in": "path", "required": true, "description": "Assistant message identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId" ], "properties": { "organizationId": { "type": "string", "format": "uuid" } } }, "examples": { "claim": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1" } } } } } }, "responses": { "200": { "description": "Assistant message claimed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "kind", "organizationId", "agentProfileId", "chatId", "userMessageId", "assistantMessageId", "expectedRevision", "prompt", "contextManifestKey", "workspaceKey", "executionToken" ], "properties": { "kind": { "type": "string", "enum": [ "chat" ] }, "organizationId": { "type": "string", "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "chatId": { "type": "string", "format": "uuid" }, "userMessageId": { "type": "string", "format": "uuid" }, "assistantMessageId": { "type": "string", "format": "uuid" }, "expectedRevision": { "type": "integer" }, "harnessSessionId": { "type": "string" }, "prompt": { "type": "string" }, "contextManifestKey": { "type": "string" }, "workspaceKey": { "type": "string" }, "executionToken": { "type": "string", "description": "Short-lived control-plane capability." } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Assistant message claimed.", "data": { "kind": "chat", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "userMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "assistantMessageId": "d4ad2b33-d18c-45c2-965d-22a883af9d89", "expectedRevision": 2, "prompt": "Review this week's support trends.", "contextManifestKey": "organizations/7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1/chats/0ce65ee0-dcd9-46c2-90a4-243f5d54dc66/context/manifest.json", "workspaceKey": "organizations/7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1/chats/0ce65ee0-dcd9-46c2-90a4-243f5d54dc66/workspace", "executionToken": "" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token.", "error": { "code": "agent_unauthorized" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Assistant message not found.", "error": { "code": "message_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "409": { "description": "Message state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Assistant message revision is stale.", "error": { "code": "message_revision_conflict" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/internal/chat/messages/{assistantMessageId}/events": { "post": { "operationId": "applyInternalChatEvent", "summary": "Apply assistant message event", "tags": [ "Internal Chat" ], "security": [ { "agentServiceToken": [] } ], "parameters": [ { "name": "assistantMessageId", "in": "path", "required": true, "description": "Assistant message identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId", "expectedRevision", "event" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "expectedRevision": { "type": "integer", "example": 2 }, "harnessSessionId": { "type": "string" }, "event": { "type": "object", "required": [ "type", "partId" ], "properties": { "type": { "type": "string", "enum": [ "text.delta", "text.replace", "tool.started", "tool.completed", "tool.failed", "file", "status" ] }, "partId": { "type": "string" } }, "additionalProperties": true } } }, "examples": { "textDelta": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "expectedRevision": 2, "harnessSessionId": "codex-session-42", "event": { "type": "text.delta", "partId": "answer", "delta": "Hello" } } }, "toolStarted": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "expectedRevision": 3, "event": { "type": "tool.started", "partId": "tool-1", "tool": "support.search", "operation": "tickets" } } } } } } }, "responses": { "200": { "description": "Chat event applied.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Chat event applied.", "data": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "assistant", "status": "processing", "revision": 2, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token.", "error": { "code": "agent_unauthorized" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Assistant message not found.", "error": { "code": "message_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "409": { "description": "Message state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Assistant message revision is stale.", "error": { "code": "message_revision_conflict" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/internal/chat/messages/{assistantMessageId}/finalize": { "post": { "operationId": "finalizeInternalChatMessage", "summary": "Finalize assistant message", "tags": [ "Internal Chat" ], "security": [ { "agentServiceToken": [] } ], "parameters": [ { "name": "assistantMessageId", "in": "path", "required": true, "description": "Assistant message identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId", "expectedRevision", "status" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "expectedRevision": { "type": "integer", "example": 5 }, "status": { "type": "string", "enum": [ "complete", "failed", "cancelled" ] }, "error": { "type": "object", "additionalProperties": true }, "harnessSessionId": { "type": "string" } } }, "examples": { "complete": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "expectedRevision": 5, "status": "complete", "harnessSessionId": "codex-session-42" } }, "failed": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "expectedRevision": 5, "status": "failed", "error": { "code": "harness_failed", "message": "Codex session ended unexpectedly.", "retryable": true } } }, "cancelled": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "expectedRevision": 6, "status": "cancelled", "harnessSessionId": "codex-session-42" } } } } } }, "responses": { "200": { "description": "Assistant message finalized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "user", "status": "complete", "revision": 1, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Assistant message finalized.", "data": { "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "replyToMessageId": null, "role": "assistant", "status": "processing", "revision": 2, "author": { "kind": "human", "displayName": "Operator" }, "parts": [ { "id": "part-1", "kind": "text", "text": "Create the onboarding plan." } ], "error": null, "completedAt": "2026-01-01T00:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token.", "error": { "code": "agent_unauthorized" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Assistant message not found.", "error": { "code": "message_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "409": { "description": "Message state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Assistant message revision is stale.", "error": { "code": "message_revision_conflict" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/internal/chat/reconcile": { "post": { "operationId": "reconcileInternalChatMessages", "summary": "Recover missed chat wakeups", "tags": [ "Internal Chat" ], "security": [ { "agentServiceToken": [] } ], "responses": { "200": { "description": "Chat messages reconciled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Chat messages reconciled.", "data": { "organizationsProcessed": 2, "pendingPublished": 1, "interruptedFinalized": 0 } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token.", "error": { "code": "agent_unauthorized" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Assistant message not found.", "error": { "code": "message_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "409": { "description": "Message state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Assistant message revision is stale.", "error": { "code": "message_revision_conflict" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/internal/run-requests/{runRequestId}/start": { "post": { "operationId": "startInternalRun", "summary": "Claim a run request and create its next attempt", "description": "Revalidates task readiness and serializes organization/profile capacity before creating the immutable attempt. A capacity conflict returns 409 without incrementing attempt or task run counters.", "tags": [ "Internal Runs" ], "security": [ { "agentServiceToken": [] } ], "parameters": [ { "name": "runRequestId", "in": "path", "required": true, "description": "Run request identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId", "runId", "workerId", "leaseToken", "leaseExpiresAt" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "leaseToken": { "type": "string" }, "runId": { "type": "string", "format": "uuid" }, "workerId": { "type": "string" }, "leaseExpiresAt": { "type": "string", "format": "date-time" } } }, "examples": { "start": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "runId": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "workerId": "worker-local-1", "leaseToken": "fence-1", "leaseExpiresAt": "2026-07-13T12:02:10.000Z" } } } } } }, "responses": { "200": { "description": "Run attempt started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "kind", "organizationId", "agentProfileId", "taskId", "runRequestId", "runId", "attempt", "executionToken" ], "properties": { "kind": { "type": "string", "enum": [ "run" ] }, "organizationId": { "type": "string", "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "taskId": { "type": "string", "format": "uuid" }, "runRequestId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" }, "attempt": { "type": "integer" }, "executionToken": { "type": "string", "description": "Short-lived control-plane capability for this exact run." } }, "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Run attempt started.", "data": { "kind": "run", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "runRequestId": "99e02964-075c-4427-9a94-d6a12dde1ac6", "runId": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "attempt": 1, "executionToken": "" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token.", "error": { "code": "agent_unauthorized" } } } } } } }, "409": { "description": "Run state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Run lease is missing, stale, or expired.", "error": { "code": "run_lease_expired" } } } } } } } } } }, "/internal/runs/{runId}/running": { "post": { "operationId": "markInternalRunRunning", "summary": "Mark a hydrated run as running", "tags": [ "Internal Runs" ], "security": [ { "agentServiceToken": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Run attempt identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId", "leaseToken", "harness", "workspaceUri" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "leaseToken": { "type": "string" }, "model": { "type": "string" }, "harness": { "type": "string" }, "workspaceUri": { "type": "string" } } }, "examples": { "running": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "leaseToken": "fence-1", "harness": "codex", "model": "gpt-5.3-codex", "workspaceUri": "s3://oblive/runs/5874578b/workspace" } } } } } }, "responses": { "200": { "description": "Run marked running.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Run marked running.", "data": { "status": "running" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token.", "error": { "code": "agent_unauthorized" } } } } } } }, "409": { "description": "Run state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Run lease is missing, stale, or expired.", "error": { "code": "run_lease_expired" } } } } } } } } } }, "/internal/runs/{runId}/heartbeat": { "post": { "operationId": "heartbeatInternalRun", "summary": "Renew an active run heartbeat and lease", "tags": [ "Internal Runs" ], "security": [ { "agentServiceToken": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Run attempt identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId", "leaseToken", "leaseExpiresAt" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "leaseToken": { "type": "string" }, "leaseExpiresAt": { "type": "string", "format": "date-time" } } }, "examples": { "heartbeat": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "leaseToken": "fence-1", "leaseExpiresAt": "2026-07-13T12:03:10.000Z" } } } } } }, "responses": { "200": { "description": "Run heartbeat recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Run heartbeat recorded.", "data": { "status": "running" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token.", "error": { "code": "agent_unauthorized" } } } } } } }, "409": { "description": "Run state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Run lease is missing, stale, or expired.", "error": { "code": "run_lease_expired" } } } } } } } } } }, "/internal/runs/{runId}/complete": { "post": { "operationId": "completeInternalRun", "summary": "Finalize a run, task, dependencies, and recovery", "description": "Finalization applies the typed outcome atomically. An exhausted replan budget opens one human override; one final amendment may consume it, and any further amendment fails the task.", "tags": [ "Internal Runs" ], "security": [ { "agentServiceToken": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Run attempt identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId", "leaseToken", "output", "usage", "harness", "workspaceUri" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "leaseToken": { "type": "string" }, "output": { "type": "object", "additionalProperties": true }, "usage": { "type": "object", "additionalProperties": true }, "model": { "type": "string" }, "harness": { "type": "string" }, "workspaceUri": { "type": "string" }, "trajectoryUri": { "type": "string" }, "logUri": { "type": "string" } } }, "examples": { "complete": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "leaseToken": "fence-1", "output": { "kind": "task_result", "result": { "kind": "completed", "summary": "Review completed.", "artifacts": [] } }, "usage": { "inputTokens": 1200, "outputTokens": 300, "toolCalls": 2, "costMinorUnits": 0 }, "harness": "codex", "workspaceUri": "s3://oblive/runs/5874578b/workspace" } } } } } }, "responses": { "200": { "description": "Run completed and dependent work reconciled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Run completed and dependent work reconciled.", "data": { "status": "running" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token.", "error": { "code": "agent_unauthorized" } } } } } } }, "409": { "description": "Run state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Run lease is missing, stale, or expired.", "error": { "code": "run_lease_expired" } } } } } } } } } }, "/internal/runs/{runId}/fail": { "post": { "operationId": "failInternalRun", "summary": "Record a fenced run failure", "tags": [ "Internal Runs" ], "security": [ { "agentServiceToken": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Run attempt identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId", "leaseToken", "error", "usage", "harness" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "leaseToken": { "type": "string" }, "error": { "type": "object", "additionalProperties": true }, "usage": { "type": "object", "additionalProperties": true }, "model": { "type": "string" }, "harness": { "type": "string" }, "workspaceUri": { "type": "string" }, "trajectoryUri": { "type": "string" }, "logUri": { "type": "string" } } }, "examples": { "failure": { "value": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "leaseToken": "fence-1", "error": { "code": "object_sync_failed", "message": "Output sync failed.", "retryable": true }, "usage": { "inputTokens": 1200, "outputTokens": 300, "toolCalls": 2, "costMinorUnits": 0 }, "harness": "codex" } } } } } }, "responses": { "200": { "description": "Run failure recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Run failure recorded.", "data": { "status": "running" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 401, "message": "Invalid agent service token.", "error": { "code": "agent_unauthorized" } } } } } } }, "409": { "description": "Run state conflict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 409, "message": "Run lease is missing, stale, or expired.", "error": { "code": "run_lease_expired" } } } } } } } } } }, "/organizations/{organizationId}/integrations": { "get": { "operationId": "listIntegrations", "summary": "List organization integrations", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Opaque alphabetical pagination cursor." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "department", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } } }, "post": { "operationId": "createCustomIntegration", "summary": "Create a custom remote MCP integration", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Custom integration created." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "/organizations/{organizationId}/integrations/{integrationRef}": { "get": { "operationId": "getIntegration", "summary": "Get an organization integration", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } } }, "patch": { "operationId": "updateCustomIntegration", "summary": "Update a custom remote MCP integration", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "delete": { "operationId": "deleteCustomIntegration", "summary": "Delete a custom remote MCP integration", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } } } }, "/organizations/{organizationId}/integrations/{integrationRef}/credential": { "put": { "operationId": "connectIntegration", "summary": "Validate credentials, discover tools, and enable an integration", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "delete": { "operationId": "removeIntegrationCredential", "summary": "Remove an integration credential", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } } } }, "/organizations/{organizationId}/integrations/{integrationRef}/oauth/google/start": { "post": { "operationId": "startGoogleWorkspaceOAuth", "summary": "Start organization Google authorization", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "/organizations/{organizationId}/integrations/{integrationRef}/oauth/mcp/start": { "post": { "operationId": "startMcpOAuth", "summary": "Start managed MCP provider authorization", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "/oauth/google/callback": { "get": { "operationId": "completeGoogleWorkspaceOAuth", "summary": "Complete Google authorization", "tags": [ "Integrations" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Redirect to the organization Integrations page." } } } }, "/oauth/mcp/callback": { "get": { "operationId": "completeMcpOAuth", "summary": "Complete managed MCP provider authorization", "tags": [ "Integrations" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Redirect to the organization Integrations page." } } } }, "/organizations/{organizationId}/integrations/{integrationRef}/discover": { "post": { "operationId": "discoverIntegrationTools", "summary": "Discover policy-eligible MCP tools", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } } } }, "/organizations/{organizationId}/integrations/{integrationRef}/status": { "patch": { "operationId": "setIntegrationStatus", "summary": "Enable or disable an integration", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "/organizations/{organizationId}/integrations/{integrationRef}/tools": { "put": { "operationId": "setIntegrationTools", "summary": "Set an integration tool allowlist and access mode", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "/organizations/{organizationId}/integrations/{integrationRef}/context-mapping": { "post": { "operationId": "requestIntegrationContextMapping", "summary": "Create or reuse a reviewed integration Context repair", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationRef", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The existing repair is in progress, or the durable repair request remains queued for recovery." }, "400": { "description": "The mapping hints are invalid or empty." }, "409": { "description": "The integration is not connected, or Context Health has not been initialized." } }, "description": "Queues a bounded Operator repair from partial business hints. It never edits canonical Context synchronously and does not affect connection success.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Partial business-context hints. At least one department, business function, task pattern, workflow key, or role is required.", "properties": { "departments": { "type": "array", "items": { "type": "string" } }, "businessFunctions": { "type": "array", "items": { "type": "string", "maxLength": 200 } }, "taskPatterns": { "type": "array", "items": { "type": "string", "maxLength": 200 } }, "workflowKeys": { "type": "array", "items": { "type": "string", "maxLength": 80 } }, "role": { "type": "string", "enum": [ "primary", "fallback", "allowed" ] } } }, "examples": { "prospecting": { "summary": "Map a newly connected prospecting integration", "value": { "departments": [ "growth" ], "businessFunctions": [ "Outbound prospecting" ], "workflowKeys": [ "qualified-lead-research" ], "role": "primary" } } } } } } } }, "/internal/agent/organizations/{organizationId}/integrations": { "get": { "operationId": "listAgentIntegrations", "summary": "List safe integrations visible to this execution", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "authorizationEpoch", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "description": "Returns control-plane readiness, enabled capabilities, access mode, department tags, and profile availability. It never returns credentials, provider endpoints, OAuth subjects, or live provider health.", "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ] } }, "/internal/agent/organizations/{organizationId}/integrations/{integrationKey}": { "get": { "operationId": "getAgentIntegration", "summary": "Get one safe integration visible to this execution", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationKey", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "authorizationEpoch", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "description": "Reads the authorization-fenced safe registry snapshot without contacting the provider.", "security": [ { "agentServiceToken": [] }, { "agentExecutionCapability": [] } ] } }, "/internal/agent/organizations/{organizationId}/integrations/resolve": { "post": { "operationId": "resolveRuntimeIntegrations", "summary": "Resolve authorized integrations for one agent run", "tags": [ "Integrations" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "agentServiceToken": [] } ] } }, "/internal/cli/integrations/{integrationId}/invocations/{invocationId}/execute": { "post": { "operationId": "executeIntegrationCli", "summary": "Classify and execute a scoped CLI invocation", "tags": [ "Integrations" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "integrationGatewayCapability": [] } ] } }, "/internal/cli/integrations/{integrationId}/invocations/{invocationId}/files/{fileId}": { "put": { "operationId": "stageIntegrationCliFile", "summary": "Stage one bounded CLI input file", "tags": [ "Integrations" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "security": [ { "integrationGatewayCapability": [] } ] }, "get": { "operationId": "downloadIntegrationCliFile", "summary": "Download one bounded CLI output file", "tags": [ "Integrations" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful organization-scoped integration response." } }, "security": [ { "integrationGatewayCapability": [] } ] } }, "/organizations/{organizationId}/tasks": { "get": { "operationId": "listTasks", "summary": "List tasks", "tags": [ "Tasks" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "id", "identifier", "title", "priority", "status", "scheduledAt", "dueAt", "createdAt", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "identifier", "in": "query", "schema": { "type": "string", "example": "ENG-1" } }, { "name": "ownerAgentProfileId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "parentId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceChatId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceMessageId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "initiative", "task", "research", "review", "learn" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "blocked", "running", "waiting_human", "done", "failed", "cancelled" ] } }, { "name": "phase", "in": "query", "schema": { "type": "string", "enum": [ "plan", "execute", "research", "review", "verify", "learn", "awaiting_descendants" ] } }, { "name": "rootTaskId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "rootOnly", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Tasks listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "example": { "id": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "identifier": "ENG-1", "identifierScope": "engineering", "identifierNumber": 1, "parentId": null, "rootTaskId": null, "depth": 0, "ownerAgentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "sourceChatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "sourceMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "kind": "task", "status": "pending", "phase": "execute", "title": "Create onboarding plan", "priority": 10, "version": 1, "graphRevision": 1, "agentRunCount": 0, "consumedAgentRunCount": 0, "replanCount": 0, "createdByRunId": null, "spec": { "objective": "Create the onboarding plan.", "inputs": [], "acceptanceCriteria": [ { "kind": "text", "description": "Plan is ready for review." } ], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 1, "maxActions": 10 } }, "state": { "blockers": [], "activeRunIds": [] }, "result": null, "dedupeKey": "onboarding-plan", "scheduledAt": "2026-01-01T00:00:00.000Z", "dueAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Tasks listed.", "data": [ { "id": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "identifier": "ENG-1", "identifierScope": "engineering", "identifierNumber": 1, "parentId": null, "rootTaskId": null, "depth": 0, "ownerAgentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "sourceChatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "sourceMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "kind": "task", "status": "pending", "phase": "execute", "title": "Create onboarding plan", "priority": 10, "version": 1, "graphRevision": 1, "agentRunCount": 0, "consumedAgentRunCount": 0, "replanCount": 0, "createdByRunId": null, "spec": { "objective": "Create the onboarding plan.", "inputs": [], "acceptanceCriteria": [ { "kind": "text", "description": "Plan is ready for review." } ], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 1, "maxActions": 10 } }, "state": { "blockers": [], "activeRunIds": [] }, "result": null, "dedupeKey": "onboarding-plan", "scheduledAt": "2026-01-01T00:00:00.000Z", "dueAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/tasks/{taskRef}": { "get": { "operationId": "getTask", "summary": "Get task", "tags": [ "Tasks" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task reference.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "identifier": "ENG-1", "identifierScope": "engineering", "identifierNumber": 1, "parentId": null, "rootTaskId": null, "depth": 0, "ownerAgentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "sourceChatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "sourceMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "kind": "task", "status": "pending", "phase": "execute", "title": "Create onboarding plan", "priority": 10, "version": 1, "graphRevision": 1, "agentRunCount": 0, "consumedAgentRunCount": 0, "replanCount": 0, "createdByRunId": null, "spec": { "objective": "Create the onboarding plan.", "inputs": [], "acceptanceCriteria": [ { "kind": "text", "description": "Plan is ready for review." } ], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 1, "maxActions": 10 } }, "state": { "blockers": [], "activeRunIds": [] }, "result": null, "dedupeKey": "onboarding-plan", "scheduledAt": "2026-01-01T00:00:00.000Z", "dueAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Task found.", "data": { "id": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "identifier": "ENG-1", "identifierScope": "engineering", "identifierNumber": 1, "parentId": null, "rootTaskId": null, "depth": 0, "ownerAgentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "sourceChatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "sourceMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "kind": "task", "status": "pending", "phase": "execute", "title": "Create onboarding plan", "priority": 10, "version": 1, "graphRevision": 1, "agentRunCount": 0, "consumedAgentRunCount": 0, "replanCount": 0, "createdByRunId": null, "spec": { "objective": "Create the onboarding plan.", "inputs": [], "acceptanceCriteria": [ { "kind": "text", "description": "Plan is ready for review." } ], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 1, "maxActions": 10 } }, "state": { "blockers": [], "activeRunIds": [] }, "result": null, "dedupeKey": "onboarding-plan", "scheduledAt": "2026-01-01T00:00:00.000Z", "dueAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Task not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Task not found.", "error": { "code": "task_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/tasks/{taskRef}/graph": { "get": { "operationId": "getTaskGraph", "summary": "Get task hierarchy and dependencies", "description": "Returns one consistent read projection for the focused task's root hierarchy, dependency edges, and boundary tasks from related roots.", "tags": [ "Tasks" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskRef", "in": "path", "required": true, "description": "Task UUID or organization-local identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task graph found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "focusTaskId", "rootTaskId", "tasks", "relatedTasks", "dependencies" ], "properties": { "focusTaskId": { "type": "string", "format": "uuid" }, "rootTaskId": { "type": "string", "format": "uuid" }, "tasks": { "type": "array", "items": { "type": "object", "additionalProperties": true, "example": { "id": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "identifier": "ENG-1", "identifierScope": "engineering", "identifierNumber": 1, "parentId": null, "rootTaskId": null, "depth": 0, "ownerAgentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "sourceChatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "sourceMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "kind": "task", "status": "pending", "phase": "execute", "title": "Create onboarding plan", "priority": 10, "version": 1, "graphRevision": 1, "agentRunCount": 0, "consumedAgentRunCount": 0, "replanCount": 0, "createdByRunId": null, "spec": { "objective": "Create the onboarding plan.", "inputs": [], "acceptanceCriteria": [ { "kind": "text", "description": "Plan is ready for review." } ], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 1, "maxActions": 10 } }, "state": { "blockers": [], "activeRunIds": [] }, "result": null, "dedupeKey": "onboarding-plan", "scheduledAt": "2026-01-01T00:00:00.000Z", "dueAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "relatedTasks": { "type": "array", "items": { "type": "object", "additionalProperties": true, "example": { "id": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "identifier": "ENG-1", "identifierScope": "engineering", "identifierNumber": 1, "parentId": null, "rootTaskId": null, "depth": 0, "ownerAgentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "sourceChatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "sourceMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "kind": "task", "status": "pending", "phase": "execute", "title": "Create onboarding plan", "priority": 10, "version": 1, "graphRevision": 1, "agentRunCount": 0, "consumedAgentRunCount": 0, "replanCount": 0, "createdByRunId": null, "spec": { "objective": "Create the onboarding plan.", "inputs": [], "acceptanceCriteria": [ { "kind": "text", "description": "Plan is ready for review." } ], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 1, "maxActions": 10 } }, "state": { "blockers": [], "activeRunIds": [] }, "result": null, "dedupeKey": "onboarding-plan", "scheduledAt": "2026-01-01T00:00:00.000Z", "dueAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "dependencies": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "example": { "focusTaskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "rootTaskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "tasks": [ { "id": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "identifier": "ENG-1", "identifierScope": "engineering", "identifierNumber": 1, "parentId": null, "rootTaskId": null, "depth": 0, "ownerAgentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "sourceChatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "sourceMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "kind": "task", "status": "pending", "phase": "execute", "title": "Create onboarding plan", "priority": 10, "version": 1, "graphRevision": 1, "agentRunCount": 0, "consumedAgentRunCount": 0, "replanCount": 0, "createdByRunId": null, "spec": { "objective": "Create the onboarding plan.", "inputs": [], "acceptanceCriteria": [ { "kind": "text", "description": "Plan is ready for review." } ], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 1, "maxActions": 10 } }, "state": { "blockers": [], "activeRunIds": [] }, "result": null, "dedupeKey": "onboarding-plan", "scheduledAt": "2026-01-01T00:00:00.000Z", "dueAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "relatedTasks": [], "dependencies": [] } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Task graph found.", "data": { "focusTaskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "rootTaskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "tasks": [ { "id": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "identifier": "ENG-1", "identifierScope": "engineering", "identifierNumber": 1, "parentId": null, "rootTaskId": null, "depth": 0, "ownerAgentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "sourceChatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "sourceMessageId": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1", "kind": "task", "status": "pending", "phase": "execute", "title": "Create onboarding plan", "priority": 10, "version": 1, "graphRevision": 1, "agentRunCount": 0, "consumedAgentRunCount": 0, "replanCount": 0, "createdByRunId": null, "spec": { "objective": "Create the onboarding plan.", "inputs": [], "acceptanceCriteria": [ { "kind": "text", "description": "Plan is ready for review." } ], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 1, "maxActions": 10 } }, "state": { "blockers": [], "activeRunIds": [] }, "result": null, "dedupeKey": "onboarding-plan", "scheduledAt": "2026-01-01T00:00:00.000Z", "dueAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "relatedTasks": [], "dependencies": [] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Task graph not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Task graph not found.", "error": { "code": "task_graph_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/task-dependencies": { "get": { "operationId": "listTaskDependencies", "summary": "List task dependencies", "tags": [ "Task Dependencies" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "description": "Cursor formatted as taskId:dependsOnTaskId.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "taskId", "dependsOnTaskId", "status", "createdAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "taskId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "dependsOnTaskId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "satisfied", "failed" ] } } ], "responses": { "200": { "description": "Task dependencies listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "organizationId", "taskId", "dependsOnTaskId", "status", "required", "condition", "createdAt" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "taskId": { "type": "string", "format": "uuid" }, "dependsOnTaskId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "satisfied", "failed" ] }, "required": { "type": "boolean" }, "condition": { "type": "object", "additionalProperties": true }, "failure": { "type": "object", "additionalProperties": true, "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "satisfiedAt": { "type": "string", "format": "date-time", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "nullable": true } }, "example": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "dependsOnTaskId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "status": "pending", "required": true, "condition": { "kind": "artifact", "artifactKind": "tracking-contract" }, "failure": null, "createdAt": "2026-01-01T00:00:00.000Z", "satisfiedAt": null, "failedAt": null } } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Task dependencies listed.", "data": [ { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "dependsOnTaskId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "status": "pending", "required": true, "condition": { "kind": "artifact", "artifactKind": "tracking-contract" }, "failure": null, "createdAt": "2026-01-01T00:00:00.000Z", "satisfiedAt": null, "failedAt": null } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/task-dependencies/{taskId}/{dependsOnTaskId}": { "get": { "operationId": "getTaskDependency", "summary": "Get task dependency", "tags": [ "Task Dependencies" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskId", "in": "path", "required": true, "description": "Dependent task identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "dependsOnTaskId", "in": "path", "required": true, "description": "Prerequisite task identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task dependency found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "organizationId", "taskId", "dependsOnTaskId", "status", "required", "condition", "createdAt" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "taskId": { "type": "string", "format": "uuid" }, "dependsOnTaskId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "satisfied", "failed" ] }, "required": { "type": "boolean" }, "condition": { "type": "object", "additionalProperties": true }, "failure": { "type": "object", "additionalProperties": true, "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "satisfiedAt": { "type": "string", "format": "date-time", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "nullable": true } }, "example": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "dependsOnTaskId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "status": "pending", "required": true, "condition": { "kind": "artifact", "artifactKind": "tracking-contract" }, "failure": null, "createdAt": "2026-01-01T00:00:00.000Z", "satisfiedAt": null, "failedAt": null } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Task dependency found.", "data": { "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "dependsOnTaskId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66", "status": "pending", "required": true, "condition": { "kind": "artifact", "artifactKind": "tracking-contract" }, "failure": null, "createdAt": "2026-01-01T00:00:00.000Z", "satisfiedAt": null, "failedAt": null }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Task dependency not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Task dependency not found.", "error": { "code": "task_dependency_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/run-requests": { "get": { "operationId": "listRunRequests", "summary": "List run requests", "tags": [ "Run Requests" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "id", "mode", "status", "priority", "availableAt", "claimedAt", "createdAt", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "taskId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "agentProfileId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "plan", "execute", "research", "review", "verify", "learn" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "claimed", "retry_wait", "succeeded", "failed", "cancelled" ] } } ], "responses": { "200": { "description": "Run requests listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "example": { "id": "99e02964-075c-4427-9a94-d6a12dde1ac6", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "mode": "execute", "status": "queued", "priority": 10, "dedupeKey": "task-execute-b12e12e7", "taskVersion": 1, "taskGraphRevision": 1, "state": {}, "availableAt": "2026-01-01T00:00:00.000Z", "claimedAt": null, "attemptCount": 0, "maxAttempts": 3, "lastRunId": null, "lastError": null, "cancelRequestedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Run requests listed.", "data": [ { "id": "99e02964-075c-4427-9a94-d6a12dde1ac6", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "mode": "execute", "status": "queued", "priority": 10, "dedupeKey": "task-execute-b12e12e7", "taskVersion": 1, "taskGraphRevision": 1, "state": {}, "availableAt": "2026-01-01T00:00:00.000Z", "claimedAt": null, "attemptCount": 0, "maxAttempts": 3, "lastRunId": null, "lastError": null, "cancelRequestedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/run-requests/{id}": { "get": { "operationId": "getRunRequest", "summary": "Get run request", "tags": [ "Run Requests" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run request found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "example": { "id": "99e02964-075c-4427-9a94-d6a12dde1ac6", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "mode": "execute", "status": "queued", "priority": 10, "dedupeKey": "task-execute-b12e12e7", "taskVersion": 1, "taskGraphRevision": 1, "state": {}, "availableAt": "2026-01-01T00:00:00.000Z", "claimedAt": null, "attemptCount": 0, "maxAttempts": 3, "lastRunId": null, "lastError": null, "cancelRequestedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Run request found.", "data": { "id": "99e02964-075c-4427-9a94-d6a12dde1ac6", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "mode": "execute", "status": "queued", "priority": 10, "dedupeKey": "task-execute-b12e12e7", "taskVersion": 1, "taskGraphRevision": 1, "state": {}, "availableAt": "2026-01-01T00:00:00.000Z", "claimedAt": null, "attemptCount": 0, "maxAttempts": 3, "lastRunId": null, "lastError": null, "cancelRequestedAt": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Run request not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Run request not found.", "error": { "code": "run_request_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/runs": { "get": { "operationId": "listRuns", "summary": "List runs", "tags": [ "Runs" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "id", "attempt", "mode", "status", "startedAt", "createdAt", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "taskId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "agentProfileId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "plan", "execute", "research", "review", "verify", "learn" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "starting", "running", "succeeded", "failed", "interrupted", "timed_out", "cancelled" ] } } ], "responses": { "200": { "description": "Runs listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "description": "Owner-safe run projection. Execution prompts, hydrated context, worker leases, and operational storage locations are intentionally excluded.", "required": [ "id", "taskId", "agentProfile", "attempt", "mode", "status", "model", "output", "error", "usage", "startedAt", "finishedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "taskId": { "type": "string", "format": "uuid" }, "agentProfile": { "type": "object", "required": [ "id", "key", "name", "kind", "department", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "operator", "chat", "department" ] }, "department": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } }, "attempt": { "type": "integer" }, "mode": { "type": "string", "enum": [ "plan", "execute", "research", "review", "verify", "learn" ] }, "status": { "type": "string", "enum": [ "starting", "running", "succeeded", "failed", "interrupted", "timed_out", "cancelled" ] }, "model": { "type": "string", "nullable": true }, "output": { "type": "object", "additionalProperties": true, "nullable": true }, "error": { "type": "object", "additionalProperties": true, "nullable": true }, "usage": { "type": "object", "additionalProperties": true }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "example": { "id": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "agentProfile": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "key": "engineering", "name": "Engineering", "kind": "department", "department": "engineering", "status": "enabled" }, "attempt": 1, "mode": "execute", "status": "succeeded", "model": "gpt-5", "output": { "kind": "task_result", "result": { "kind": "completed", "summary": "Created and verified the onboarding plan.", "artifacts": [] } }, "error": null, "usage": { "inputTokens": 0, "outputTokens": 0, "toolCalls": 0, "costMinorUnits": 0 }, "startedAt": "2026-01-01T00:01:00.000Z", "finishedAt": "2026-01-01T00:03:00.000Z", "createdAt": "2026-01-01T00:01:00.000Z", "updatedAt": "2026-01-01T00:01:00.000Z" } } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Runs listed.", "data": [ { "id": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "agentProfile": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "key": "engineering", "name": "Engineering", "kind": "department", "department": "engineering", "status": "enabled" }, "attempt": 1, "mode": "execute", "status": "succeeded", "model": "gpt-5", "output": { "kind": "task_result", "result": { "kind": "completed", "summary": "Created and verified the onboarding plan.", "artifacts": [] } }, "error": null, "usage": { "inputTokens": 0, "outputTokens": 0, "toolCalls": 0, "costMinorUnits": 0 }, "startedAt": "2026-01-01T00:01:00.000Z", "finishedAt": "2026-01-01T00:03:00.000Z", "createdAt": "2026-01-01T00:01:00.000Z", "updatedAt": "2026-01-01T00:01:00.000Z" } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/runs/{id}": { "get": { "operationId": "getRun", "summary": "Get run", "tags": [ "Runs" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "description": "Owner-safe run projection. Execution prompts, hydrated context, worker leases, and operational storage locations are intentionally excluded.", "required": [ "id", "taskId", "agentProfile", "attempt", "mode", "status", "model", "output", "error", "usage", "startedAt", "finishedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "taskId": { "type": "string", "format": "uuid" }, "agentProfile": { "type": "object", "required": [ "id", "key", "name", "kind", "department", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "operator", "chat", "department" ] }, "department": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } }, "attempt": { "type": "integer" }, "mode": { "type": "string", "enum": [ "plan", "execute", "research", "review", "verify", "learn" ] }, "status": { "type": "string", "enum": [ "starting", "running", "succeeded", "failed", "interrupted", "timed_out", "cancelled" ] }, "model": { "type": "string", "nullable": true }, "output": { "type": "object", "additionalProperties": true, "nullable": true }, "error": { "type": "object", "additionalProperties": true, "nullable": true }, "usage": { "type": "object", "additionalProperties": true }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "example": { "id": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "agentProfile": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "key": "engineering", "name": "Engineering", "kind": "department", "department": "engineering", "status": "enabled" }, "attempt": 1, "mode": "execute", "status": "succeeded", "model": "gpt-5", "output": { "kind": "task_result", "result": { "kind": "completed", "summary": "Created and verified the onboarding plan.", "artifacts": [] } }, "error": null, "usage": { "inputTokens": 0, "outputTokens": 0, "toolCalls": 0, "costMinorUnits": 0 }, "startedAt": "2026-01-01T00:01:00.000Z", "finishedAt": "2026-01-01T00:03:00.000Z", "createdAt": "2026-01-01T00:01:00.000Z", "updatedAt": "2026-01-01T00:01:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Run found.", "data": { "id": "5874578b-65c7-4d72-b3de-2bc24a8b421e", "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64", "agentProfile": { "id": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "key": "engineering", "name": "Engineering", "kind": "department", "department": "engineering", "status": "enabled" }, "attempt": 1, "mode": "execute", "status": "succeeded", "model": "gpt-5", "output": { "kind": "task_result", "result": { "kind": "completed", "summary": "Created and verified the onboarding plan.", "artifacts": [] } }, "error": null, "usage": { "inputTokens": 0, "outputTokens": 0, "toolCalls": 0, "costMinorUnits": 0 }, "startedAt": "2026-01-01T00:01:00.000Z", "finishedAt": "2026-01-01T00:03:00.000Z", "createdAt": "2026-01-01T00:01:00.000Z", "updatedAt": "2026-01-01T00:01:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Run not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Run not found.", "error": { "code": "run_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/schedules": { "get": { "operationId": "listSchedules", "summary": "List schedules", "tags": [ "Schedules" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "example": 50 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "id", "key", "name", "status", "nextRunAt", "lastRunAt", "createdAt", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "agentProfileId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "enabled", "disabled" ] } }, { "name": "origin", "in": "query", "schema": { "type": "string", "enum": [ "system", "agent" ] } }, { "name": "department", "in": "query", "schema": { "type": "string", "enum": [ "growth", "engineering", "support" ] } } ], "responses": { "200": { "description": "Schedules listed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organizationId", "agentProfileId", "key", "name", "status", "origin", "createdByAgentProfileId", "sourceRunId", "sourceChatId", "sourceMessageId", "trigger", "taskTemplate", "state" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "origin": { "type": "string", "enum": [ "system", "agent" ] }, "createdByAgentProfileId": { "type": "string", "format": "uuid", "nullable": true }, "sourceRunId": { "type": "string", "format": "uuid", "nullable": true }, "sourceChatId": { "type": "string", "format": "uuid", "nullable": true }, "sourceMessageId": { "type": "string", "format": "uuid", "nullable": true }, "trigger": { "type": "object", "additionalProperties": true }, "taskTemplate": { "type": "object", "additionalProperties": true }, "state": { "type": "object", "additionalProperties": true } }, "additionalProperties": true, "example": { "id": "59ea19f8-eb2f-4722-9cb5-92ed024c5a32", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "key": "weekly-support-review", "name": "Weekly Support Review", "status": "enabled", "origin": "system", "createdByAgentProfileId": null, "sourceRunId": null, "sourceChatId": null, "sourceMessageId": null, "trigger": { "kind": "interval", "everyMinutes": 10080, "timezone": "UTC" }, "taskTemplate": { "title": "Review support queue", "kind": "task", "ownerAgentProfileKey": "support", "spec": { "objective": "Review unresolved support conversations.", "inputs": [], "acceptanceCriteria": [], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 0, "maxActions": 0 } }, "priority": 10 }, "state": {}, "nextRunAt": "2026-01-05T09:00:00.000Z", "lastRunAt": null, "lastError": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } } }, "meta": { "type": "object", "additionalProperties": true }, "pagination": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Schedules listed.", "data": [ { "id": "59ea19f8-eb2f-4722-9cb5-92ed024c5a32", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "key": "weekly-support-review", "name": "Weekly Support Review", "status": "enabled", "origin": "system", "createdByAgentProfileId": null, "sourceRunId": null, "sourceChatId": null, "sourceMessageId": null, "trigger": { "kind": "interval", "everyMinutes": 10080, "timezone": "UTC" }, "taskTemplate": { "title": "Review support queue", "kind": "task", "ownerAgentProfileKey": "support", "spec": { "objective": "Review unresolved support conversations.", "inputs": [], "acceptanceCriteria": [], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 0, "maxActions": 0 } }, "priority": 10 }, "state": {}, "nextRunAt": "2026-01-05T09:00:00.000Z", "lastRunAt": null, "lastError": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "pagination": { "cursor": null, "limit": 50, "nextCursor": null, "previousCursor": null, "hasNextPage": false, "hasPreviousPage": false }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } }, "/organizations/{organizationId}/schedules/{scheduleRef}": { "get": { "operationId": "getSchedule", "summary": "Get schedule", "tags": [ "Schedules" ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "scheduleRef", "in": "path", "required": true, "description": "Schedule reference.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Schedule found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "data", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "id", "organizationId", "agentProfileId", "key", "name", "status", "origin", "createdByAgentProfileId", "sourceRunId", "sourceChatId", "sourceMessageId", "trigger", "taskTemplate", "state" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "origin": { "type": "string", "enum": [ "system", "agent" ] }, "createdByAgentProfileId": { "type": "string", "format": "uuid", "nullable": true }, "sourceRunId": { "type": "string", "format": "uuid", "nullable": true }, "sourceChatId": { "type": "string", "format": "uuid", "nullable": true }, "sourceMessageId": { "type": "string", "format": "uuid", "nullable": true }, "trigger": { "type": "object", "additionalProperties": true }, "taskTemplate": { "type": "object", "additionalProperties": true }, "state": { "type": "object", "additionalProperties": true } }, "additionalProperties": true, "example": { "id": "59ea19f8-eb2f-4722-9cb5-92ed024c5a32", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "key": "weekly-support-review", "name": "Weekly Support Review", "status": "enabled", "origin": "system", "createdByAgentProfileId": null, "sourceRunId": null, "sourceChatId": null, "sourceMessageId": null, "trigger": { "kind": "interval", "everyMinutes": 10080, "timezone": "UTC" }, "taskTemplate": { "title": "Review support queue", "kind": "task", "ownerAgentProfileKey": "support", "spec": { "objective": "Review unresolved support conversations.", "inputs": [], "acceptanceCriteria": [], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 0, "maxActions": 0 } }, "priority": 10 }, "state": {}, "nextRunAt": "2026-01-05T09:00:00.000Z", "lastRunAt": null, "lastError": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": true, "statusCode": 200, "message": "Schedule found.", "data": { "id": "59ea19f8-eb2f-4722-9cb5-92ed024c5a32", "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1", "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d", "key": "weekly-support-review", "name": "Weekly Support Review", "status": "enabled", "origin": "system", "createdByAgentProfileId": null, "sourceRunId": null, "sourceChatId": null, "sourceMessageId": null, "trigger": { "kind": "interval", "everyMinutes": 10080, "timezone": "UTC" }, "taskTemplate": { "title": "Review support queue", "kind": "task", "ownerAgentProfileKey": "support", "spec": { "objective": "Review unresolved support conversations.", "inputs": [], "acceptanceCriteria": [], "budget": { "maxAgentRuns": 6, "maxAttemptsPerPhase": 3, "maxReplans": 0, "maxActions": 0 } }, "priority": 10 }, "state": {}, "nextRunAt": "2026-01-05T09:00:00.000Z", "lastRunAt": null, "lastError": null, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 400, "message": "Validation failed.", "error": { "code": "validation_failed", "issues": [ { "path": "organizationId", "message": "Must be a valid UUID.", "code": "invalid_format" } ] }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } }, "404": { "description": "Schedule not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "statusCode", "message", "error", "meta" ], "properties": { "success": { "type": "boolean", "example": false }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "success": false, "statusCode": 404, "message": "Schedule not found.", "error": { "code": "schedule_not_found" }, "meta": { "timestamp": "2026-01-01T00:00:00.000Z" } } } } } } } } } } } }