builderz-labs / mission-control
5,830 TypeScriptSelf-hosted control plane for AI agents: dispatch tasks, review runs, track spend, and operate OpenClaw, Claude Code, Codex, and other runtimes.
Mission Control API Specification
Located in openapi.json on branch HEAD
3.1.0
JSON
144 Endpoints
330.6 KB
Operations & Route Endpoints (100)
Raw JSON Specification
{
"openapi": "3.1.0",
"info": {
"title": "Mission Control API",
"version": "1.3.0",
"description": "AI Agent Orchestration Platform API"
},
"servers": [
{
"url": "/",
"description": "Current server"
}
],
"security": [
{
"sessionCookie": []
},
{
"apiKey": []
}
],
"tags": [
{
"name": "Auth",
"description": "Authentication and user management"
},
{
"name": "Agents",
"description": "Agent lifecycle and configuration"
},
{
"name": "Tasks",
"description": "Task management and assignment"
},
{
"name": "Chat",
"description": "Conversations and messaging"
},
{
"name": "Tokens",
"description": "Token usage tracking and cost analysis"
},
{
"name": "Sessions",
"description": "Gateway and local runtime session management"
},
{
"name": "Webhooks",
"description": "Webhook configuration and delivery"
},
{
"name": "Alerts",
"description": "Alert rule management"
},
{
"name": "Workflows",
"description": "Workflow template management"
},
{
"name": "Pipelines",
"description": "Pipeline orchestration"
},
{
"name": "Monitoring",
"description": "Activities, logs, events, and notifications"
},
{
"name": "Admin",
"description": "System administration and configuration"
},
{
"name": "Super Admin",
"description": "Multi-tenant provisioning"
},
{
"name": "Connections",
"description": "Direct CLI tool connections"
},
{
"name": "Projects",
"description": "Project management and task grouping"
},
{
"name": "Mentions",
"description": "User and agent mention autocomplete"
},
{
"name": "Quality",
"description": "Quality review gate for tasks"
},
{
"name": "Releases",
"description": "Release and version checking"
},
{
"name": "Docs",
"description": "API documentation"
}
],
"paths": {
"/api/activities": {
"get": {
"tags": [
"Monitoring"
],
"summary": "List activities",
"operationId": "listActivities",
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "actor",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "entity_type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 50
}
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Activity list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"activities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"type": {
"type": "string"
},
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "integer"
},
"actor": {
"type": "string"
},
"description": {
"type": "string"
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "integer"
}
}
}
},
"total": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/adapters": {
"get": {
"tags": [
"Agents"
],
"summary": "Get /api/adapters",
"operationId": "getApiAdapters",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Agents"
],
"summary": "Post /api/adapters",
"operationId": "postApiAdapters",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/agent-runtimes": {
"get": {
"tags": [
"Agents"
],
"summary": "Get agent runtime status",
"operationId": "getAgentRuntimes",
"responses": {
"200": {
"description": "Runtime detection and active install jobs"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Agents"
],
"summary": "Manage agent runtime actions",
"operationId": "postAgentRuntimes",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"install",
"job-status",
"docker-compose",
"detect"
]
},
"runtime": {
"type": "string",
"enum": [
"openclaw",
"hermes",
"claude",
"codex",
"opencode"
]
},
"mode": {
"type": "string",
"enum": [
"local",
"docker"
]
},
"jobId": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Runtime action response"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/agents": {
"get": {
"tags": [
"Agents"
],
"summary": "List agents",
"operationId": "listAgents",
"parameters": [
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"online",
"offline",
"busy",
"idle",
"error"
]
}
},
{
"name": "role",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 50,
"maximum": 200
}
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Paginated agent list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Agent"
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Agents"
],
"summary": "Create agent",
"operationId": "createAgent",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"role"
],
"properties": {
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"session_key": {
"type": "string"
},
"soul_content": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"online",
"offline",
"busy",
"idle",
"error"
],
"default": "offline"
},
"config": {
"type": "object"
},
"template": {
"type": "string"
},
"gateway_config": {
"type": "object"
},
"write_to_gateway": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Agent created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agent": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"description": "Agent name already exists",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"put": {
"tags": [
"Agents"
],
"summary": "Update agent by name",
"operationId": "updateAgentByName",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"online",
"offline",
"busy",
"idle",
"error"
]
},
"last_activity": {
"type": "string"
},
"config": {
"type": "object"
},
"session_key": {
"type": "string"
},
"soul_content": {
"type": "string"
},
"role": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Agent updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/agents/comms": {
"get": {
"tags": [
"Agents"
],
"summary": "Get agent communications",
"operationId": "getAgentComms",
"parameters": [
{
"name": "agent",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 50
}
}
],
"responses": {
"200": {
"description": "Agent communication log",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"from_agent": {
"type": "string"
},
"to_agent": {
"type": "string"
},
"content": {
"type": "string"
},
"type": {
"type": "string"
},
"created_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/agents/message": {
"post": {
"tags": [
"Agents"
],
"summary": "Send message between agents",
"operationId": "sendAgentMessage",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"from",
"to",
"content"
],
"properties": {
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"content": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Message sent",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"id": {
"type": "integer"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/agents/sync": {
"get": {
"tags": [
"Agents"
],
"summary": "Preview agent sync diff",
"operationId": "previewAgentSyncDiff",
"responses": {
"200": {
"description": "Sync diff preview",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Agents"
],
"summary": "Sync agents from gateway config",
"operationId": "syncAgents",
"responses": {
"200": {
"description": "Sync results",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"synced": {
"type": "integer"
},
"created": {
"type": "integer"
},
"updated": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/agents/{id}": {
"get": {
"tags": [
"Agents"
],
"summary": "Get agent by ID",
"operationId": "getAgent",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Agent details",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agent": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"put": {
"tags": [
"Agents"
],
"summary": "Update agent by ID",
"operationId": "updateAgent",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"status": {
"type": "string"
},
"config": {
"type": "object"
},
"session_key": {
"type": "string"
},
"soul_content": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Agent updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agent": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"tags": [
"Agents"
],
"summary": "Delete agent",
"operationId": "deleteAgent",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Agent deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/agents/{id}/attribution": {
"get": {
"tags": [
"Agents"
],
"summary": "Get attribution report for an agent",
"description": "Self-scope by default. Requester must match target agent (`x-agent-name` or username), unless admin uses `?privileged=1`.",
"operationId": "getAgentAttribution",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hours",
"in": "query",
"required": false,
"description": "Time window in hours, integer range 1..720. Defaults to 24.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 720,
"default": 24
}
},
{
"name": "section",
"in": "query",
"required": false,
"description": "Comma-separated subset of identity,audit,mutations,cost. Defaults to all.",
"schema": {
"type": "string",
"example": "identity,audit"
}
},
{
"name": "privileged",
"in": "query",
"required": false,
"description": "Set to 1 for admin override of self-scope checks.",
"schema": {
"type": "string",
"enum": [
"1"
]
}
},
{
"name": "x-agent-name",
"in": "header",
"required": false,
"description": "Attribution identity header used for self-scope authorization.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Attribution report"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/agents/{id}/diagnostics": {
"get": {
"tags": [
"Agents"
],
"summary": "Get self diagnostics for an agent",
"description": "Self-scoped diagnostics by default. Cross-agent access requires `privileged=1` with admin credentials. Trend alerts are informational signals derived from current-vs-previous window deltas (error spikes, throughput drops, activity stalls).",
"operationId": "getAgentDiagnostics",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Agent numeric ID or name."
},
{
"name": "hours",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 720,
"default": 24
},
"description": "Diagnostics window in hours."
},
{
"name": "section",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated sections: summary,tasks,errors,activity,trends,tokens."
},
{
"name": "privileged",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"1"
]
},
"description": "Set to `1` to allow explicit admin cross-agent diagnostics access."
}
],
"responses": {
"200": {
"description": "Diagnostics payload",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agent": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"timeframe": {
"type": "object",
"properties": {
"hours": {
"type": "integer"
},
"since": {
"type": "integer"
},
"until": {
"type": "integer"
}
}
},
"summary": {
"type": "object"
},
"tasks": {
"type": "object"
},
"errors": {
"type": "object"
},
"activity": {
"type": "object"
},
"trends": {
"type": "object",
"properties": {
"current_period": {
"type": "object"
},
"previous_period": {
"type": "object"
},
"change": {
"type": "object"
},
"alerts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"level": {
"type": "string",
"enum": [
"info",
"warning"
]
},
"message": {
"type": "string"
}
}
}
}
}
},
"tokens": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/agents/{id}/heartbeat": {
"get": {
"tags": [
"Agents"
],
"summary": "Check agent work items",
"operationId": "getAgentHeartbeat",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Heartbeat data with pending work items",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agent": {
"type": "string"
},
"pending_tasks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"messages": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"post": {
"tags": [
"Agents"
],
"summary": "Trigger manual heartbeat",
"operationId": "triggerAgentHeartbeat",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Heartbeat triggered",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/agents/{id}/memory": {
"get": {
"tags": [
"Agents"
],
"summary": "Get agent memory",
"operationId": "getAgentMemory",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Agent memory data",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"put": {
"tags": [
"Agents"
],
"summary": "Update agent memory",
"operationId": "updateAgentMemory",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Memory updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"delete": {
"tags": [
"Agents"
],
"summary": "Clear agent memory",
"operationId": "deleteAgentMemory",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Agent ID or name"
}
],
"responses": {
"200": {
"description": "Memory cleared",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"working_memory": {
"type": "string"
},
"updated_at": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/agents/{id}/soul": {
"get": {
"tags": [
"Agents"
],
"summary": "Get agent soul config",
"operationId": "getAgentSoul",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Soul configuration",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"soul_content": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"put": {
"tags": [
"Agents"
],
"summary": "Update agent soul config",
"operationId": "updateAgentSoul",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"soul_content"
],
"properties": {
"soul_content": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Soul updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"tags": [
"API"
],
"summary": "List or load soul templates",
"operationId": "patch_api_agents_id_soul",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
},
"/api/agents/{id}/wake": {
"post": {
"tags": [
"Agents"
],
"summary": "Wake an agent",
"operationId": "wakeAgent",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reason": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Agent woken",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/alerts": {
"get": {
"tags": [
"Alerts"
],
"summary": "List alert rules",
"operationId": "listAlertRules",
"responses": {
"200": {
"description": "Alert rule list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"rules": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AlertRule"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Alerts"
],
"summary": "Create alert rule or evaluate rules",
"operationId": "createAlertRule",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"title": "CreateRule",
"required": [
"name",
"entity_type",
"condition_field",
"condition_operator",
"condition_value"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"entity_type": {
"type": "string",
"enum": [
"agent",
"task",
"session",
"activity"
]
},
"condition_field": {
"type": "string"
},
"condition_operator": {
"type": "string",
"enum": [
"equals",
"not_equals",
"greater_than",
"less_than",
"contains",
"count_above",
"count_below",
"age_minutes_above"
]
},
"condition_value": {
"type": "string"
},
"action_type": {
"type": "string",
"default": "notification"
},
"action_config": {
"type": "object"
},
"cooldown_minutes": {
"type": "integer",
"default": 60
}
}
},
{
"type": "object",
"title": "EvaluateRules",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"const": "evaluate"
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Rules evaluated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"evaluated": {
"type": "integer"
},
"triggered": {
"type": "integer"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rule_id": {
"type": "integer"
},
"rule_name": {
"type": "string"
},
"triggered": {
"type": "boolean"
},
"reason": {
"type": "string"
}
}
}
}
}
}
}
}
},
"201": {
"description": "Rule created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"rule": {
"$ref": "#/components/schemas/AlertRule"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"put": {
"tags": [
"Alerts"
],
"summary": "Update alert rule",
"operationId": "updateAlertRule",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entity_type": {
"type": "string"
},
"condition_field": {
"type": "string"
},
"condition_operator": {
"type": "string"
},
"condition_value": {
"type": "string"
},
"action_type": {
"type": "string"
},
"action_config": {
"type": "object"
},
"cooldown_minutes": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Rule updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"rule": {
"$ref": "#/components/schemas/AlertRule"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"tags": [
"Alerts"
],
"summary": "Delete alert rule",
"operationId": "deleteAlertRule",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Rule deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/audit": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Get audit log",
"operationId": "getAuditLog",
"parameters": [
{
"name": "action",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "actor",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 100
}
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Audit log entries",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"action": {
"type": "string"
},
"actor": {
"type": "string"
},
"target_type": {
"type": "string"
},
"target_id": {
"type": "integer"
},
"detail": {
"type": "object"
},
"ip_address": {
"type": "string"
},
"created_at": {
"type": "integer"
}
}
}
},
"total": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/auth/access-requests": {
"get": {
"tags": [
"Auth"
],
"summary": "List access requests",
"operationId": "listAccessRequests",
"responses": {
"200": {
"description": "Access request list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"requests": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"username": {
"type": "string"
},
"email": {
"type": "string"
},
"reason": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"created_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Auth"
],
"summary": "Approve or reject access request",
"operationId": "handleAccessRequest",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"action"
],
"properties": {
"id": {
"type": "integer"
},
"action": {
"type": "string",
"enum": [
"approve",
"reject"
]
},
"role": {
"type": "string",
"enum": [
"admin",
"operator",
"viewer"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Request processed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/auth/google": {
"post": {
"tags": [
"Auth"
],
"summary": "Login with Google ID token",
"operationId": "googleLogin",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"credential"
],
"properties": {
"credential": {
"type": "string",
"description": "Google identity credential token"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Login successful"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/auth/login": {
"post": {
"tags": [
"Auth"
],
"summary": "Login with credentials",
"operationId": "login",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"username",
"password"
],
"properties": {
"username": {
"type": "string"
},
"password": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Login successful. Sets __Host-mc-session cookie (HTTPS) or mc-session (HTTP).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/User"
}
}
}
}
},
"headers": {
"Set-Cookie": {
"schema": {
"type": "string"
},
"description": "__Host-mc-session cookie (secure HTTPS) or mc-session (HTTP legacy)"
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"description": "Invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/auth/logout": {
"post": {
"tags": [
"Auth"
],
"summary": "Logout and clear session",
"operationId": "logout",
"responses": {
"200": {
"description": "Session cleared"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/auth/me": {
"get": {
"tags": [
"Auth"
],
"summary": "Get current user info",
"operationId": "getCurrentUser",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/User"
}
}
}
}
},
"description": "Current user"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"patch": {
"tags": [
"Auth"
],
"summary": "Update current user profile",
"operationId": "updateCurrentUser",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"current_password": {
"type": "string"
},
"new_password": {
"type": "string",
"minLength": 8
},
"display_name": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Profile updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"user": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Incorrect password or API key user"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/auth/users": {
"get": {
"tags": [
"Auth"
],
"summary": "List users",
"operationId": "listUsers",
"responses": {
"200": {
"description": "User list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Auth"
],
"summary": "Create user",
"operationId": "createUser",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"username",
"password",
"role"
],
"properties": {
"username": {
"type": "string"
},
"password": {
"type": "string"
},
"display_name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"admin",
"operator",
"viewer"
]
},
"email": {
"type": "string"
}
}
}
}
}
},
"responses": {
"201": {
"description": "User created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"description": "Username already exists",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"put": {
"tags": [
"Auth"
],
"summary": "Update user",
"operationId": "updateUser",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"display_name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"admin",
"operator",
"viewer"
]
},
"email": {
"type": "string"
},
"password": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"delete": {
"tags": [
"Auth"
],
"summary": "Delete user",
"operationId": "deleteUser",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/backup": {
"get": {
"tags": [
"Admin"
],
"summary": "List existing backups",
"operationId": "listBackups",
"responses": {
"200": {
"description": "Backup list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"backups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"size": {
"type": "integer"
},
"created_at": {
"type": "integer"
}
}
}
},
"dir": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Trigger backup",
"operationId": "triggerBackup",
"responses": {
"200": {
"description": "Backup completed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"path": {
"type": "string"
},
"size_bytes": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"delete": {
"tags": [
"Admin"
],
"summary": "Delete a specific backup",
"operationId": "deleteBackup",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Backup deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/chat/conversations": {
"get": {
"tags": [
"Chat"
],
"summary": "List conversations",
"operationId": "listConversations",
"responses": {
"200": {
"description": "Conversation list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"conversations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"participants": {
"type": "array",
"items": {
"type": "string"
}
},
"last_message": {
"type": "string"
},
"updated_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/chat/messages": {
"get": {
"tags": [
"Chat"
],
"summary": "List messages",
"operationId": "listMessages",
"parameters": [
{
"name": "conversation_id",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 50
}
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Message list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"conversation_id": {
"type": "integer"
},
"sender": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Chat"
],
"summary": "Send message",
"operationId": "sendMessage",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"conversation_id": {
"type": "integer"
},
"content": {
"type": "string"
},
"recipient": {
"type": "string"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Message sent",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/chat/messages/{id}": {
"get": {
"tags": [
"Chat"
],
"summary": "Get message by ID",
"operationId": "getMessage",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Message details",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"tags": [
"Chat"
],
"summary": "Update message state",
"operationId": "updateMessage",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"read": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Message updated"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/claude/sessions": {
"get": {
"tags": [
"Sessions"
],
"summary": "List Claude CLI sessions",
"operationId": "listClaudeSessions",
"responses": {
"200": {
"description": "Session list"
}
}
},
"post": {
"tags": [
"Sessions"
],
"summary": "Register a Claude CLI session",
"operationId": "registerClaudeSession",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"session_id": {
"type": "string"
},
"agent_name": {
"type": "string"
},
"model": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Session registered"
}
}
}
},
"/api/cleanup": {
"get": {
"tags": [
"Admin"
],
"summary": "Preview retention policy and stale data counts",
"operationId": "previewCleanup",
"responses": {
"200": {
"description": "Retention preview",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"retention": {
"type": "object"
},
"preview": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Trigger cleanup of old data",
"operationId": "triggerCleanup",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"older_than_days": {
"type": "integer",
"default": 30
}
}
}
}
}
},
"responses": {
"200": {
"description": "Cleanup results",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"deleted": {
"type": "object"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/connect": {
"post": {
"tags": [
"Connections"
],
"summary": "Register a direct CLI connection",
"description": "Registers a CLI tool directly without a gateway. Auto-creates agent if name doesn't exist.",
"operationId": "registerConnection",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tool_name",
"agent_name"
],
"properties": {
"tool_name": {
"type": "string"
},
"tool_version": {
"type": "string"
},
"agent_name": {
"type": "string"
},
"agent_role": {
"type": "string"
},
"metadata": {
"type": "object"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Connection registered",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"connection_id": {
"type": "string",
"format": "uuid"
},
"agent_id": {
"type": "integer"
},
"agent_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"connected"
]
},
"sse_url": {
"type": "string"
},
"heartbeat_url": {
"type": "string"
},
"token_report_url": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"get": {
"tags": [
"Connections"
],
"summary": "List all direct connections",
"operationId": "listConnections",
"responses": {
"200": {
"description": "List of connections",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"connections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"agent_id": {
"type": "integer"
},
"agent_name": {
"type": "string"
},
"tool_name": {
"type": "string"
},
"tool_version": {
"type": "string"
},
"connection_id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"connected",
"disconnected"
]
},
"last_heartbeat": {
"type": "integer"
},
"created_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"delete": {
"tags": [
"Connections"
],
"summary": "Disconnect a CLI connection",
"operationId": "disconnectConnection",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"connection_id"
],
"properties": {
"connection_id": {
"type": "string",
"format": "uuid"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Disconnected",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"disconnected"
]
},
"connection_id": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/cron": {
"get": {
"tags": [
"Admin"
],
"summary": "Get cron jobs",
"operationId": "getCronJobs",
"parameters": [
{
"name": "action",
"in": "query",
"schema": {
"type": "string",
"enum": [
"list",
"logs"
],
"default": "list"
}
}
],
"responses": {
"200": {
"description": "Cron job list or logs",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"schedule": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"last_run": {
"type": "integer"
},
"last_status": {
"type": "string"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Manage cron jobs",
"operationId": "manageCronJobs",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"toggle",
"trigger",
"add",
"remove"
]
},
"name": {
"type": "string"
},
"schedule": {
"type": "string"
},
"command": {
"type": "string"
},
"enabled": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Action applied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/gateways/control": {
"get": {
"tags": [
"Agents"
],
"summary": "Get gateway control status",
"operationId": "getGatewayControlStatus",
"responses": {
"200": {
"description": "Gateway status list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"gateways": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"hermes",
"openclaw"
]
},
"name": {
"type": "string"
},
"installed": {
"type": "boolean"
},
"running": {
"type": "boolean"
},
"port": {
"type": "integer"
},
"pid": {
"type": [
"integer",
"null"
]
},
"version": {
"type": [
"string",
"null"
]
},
"error": {
"type": "string"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Agents"
],
"summary": "Control a gateway",
"operationId": "controlGateway",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"gateway",
"action"
],
"properties": {
"gateway": {
"type": "string",
"enum": [
"hermes",
"openclaw"
]
},
"action": {
"type": "string",
"enum": [
"start",
"stop",
"restart",
"diagnose"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Gateway control result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"output": {
"type": "string"
},
"status": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string"
},
"installed": {
"type": "boolean"
},
"running": {
"type": "boolean"
},
"port": {
"type": "integer"
},
"pid": {
"type": [
"integer",
"null"
]
},
"version": {
"type": [
"string",
"null"
]
},
"error": {
"type": "string"
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/docs": {
"get": {
"tags": [
"Docs"
],
"summary": "Get OpenAPI specification",
"operationId": "getOpenApiSpec",
"security": [],
"responses": {
"200": {
"description": "OpenAPI 3.1 JSON spec"
}
}
}
},
"/api/events": {
"get": {
"tags": [
"Monitoring"
],
"summary": "SSE stream for real-time events",
"operationId": "getEventStream",
"responses": {
"200": {
"description": "Server-Sent Events stream",
"content": {
"text/event-stream": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/exec-approvals": {
"get": {
"tags": [
"Admin"
],
"summary": "Get /api/exec-approvals",
"operationId": "getApiExecApprovals",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Post /api/exec-approvals",
"operationId": "postApiExecApprovals",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"put": {
"tags": [
"Admin"
],
"summary": "Put /api/exec-approvals",
"operationId": "putApiExecApprovals",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/export": {
"get": {
"tags": [
"Admin"
],
"summary": "Export data",
"operationId": "exportData",
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"type": "string",
"enum": [
"tasks",
"agents",
"activities",
"all"
]
}
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string",
"enum": [
"json",
"csv"
],
"default": "json"
}
}
],
"responses": {
"200": {
"description": "Exported data",
"content": {
"application/json": {
"schema": {
"type": "object"
}
},
"text/csv": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/gateway-config": {
"get": {
"tags": [
"Admin"
],
"summary": "Read gateway config",
"operationId": "getGatewayConfig",
"responses": {
"200": {
"description": "Gateway configuration",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"put": {
"tags": [
"Admin"
],
"summary": "Update gateway config",
"operationId": "updateGatewayConfig",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Config updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/frameworks": {
"get": {
"tags": [
"Config"
],
"summary": "List supported frameworks",
"description": "Returns all supported agent frameworks with connection info and optional templates.",
"operationId": "listFrameworks",
"parameters": [
{
"name": "framework",
"in": "query",
"description": "Filter to a specific framework (e.g., langgraph)",
"schema": {
"type": "string"
}
},
{
"name": "templates",
"in": "query",
"description": "Include available templates when set to 'true'",
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
}
}
],
"responses": {
"200": {
"description": "Framework list or single framework detail",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"frameworks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
},
"framework": {
"type": "object"
},
"templates": {
"type": "array"
}
}
}
}
}
}
}
}
},
"/api/gateways": {
"get": {
"tags": [
"Admin"
],
"summary": "List gateways",
"operationId": "listGateways",
"responses": {
"200": {
"description": "Gateway list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"gateways": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"status": {
"type": "string"
},
"last_health_check": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Add gateway",
"operationId": "addGateway",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Gateway added",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"put": {
"tags": [
"Admin"
],
"summary": "Update gateway",
"operationId": "updateGateway",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"url": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Gateway updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"delete": {
"tags": [
"Admin"
],
"summary": "Delete gateway",
"operationId": "deleteGateway",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Gateway deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/gateways/connect": {
"post": {
"tags": [
"Admin"
],
"summary": "Resolve websocket connect payload for a gateway",
"operationId": "connectGateway",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Resolved websocket URL and token metadata",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"ws_url": {
"type": "string"
},
"token": {
"type": "string"
},
"token_set": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/gateways/health": {
"post": {
"tags": [
"Admin"
],
"summary": "Probe gateway health",
"operationId": "probeGatewayHealth",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"gateway_id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Health check results",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"healthy": {
"type": "boolean"
},
"latency_ms": {
"type": "number"
},
"details": {
"type": "object"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/github": {
"get": {
"tags": [
"Admin"
],
"summary": "Get GitHub integration status",
"operationId": "getGithubStatus",
"responses": {
"200": {
"description": "GitHub integration status"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Sync GitHub issues",
"operationId": "syncGithubIssues",
"responses": {
"200": {
"description": "Sync result"
}
}
}
},
"/api/integrations": {
"get": {
"tags": [
"Admin"
],
"summary": "List integrations",
"operationId": "listIntegrations",
"responses": {
"200": {
"description": "Integration list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"integrations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Integration actions (enable, disable, test, configure)",
"operationId": "integrationAction",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action",
"id"
],
"properties": {
"action": {
"type": "string",
"enum": [
"enable",
"disable",
"test",
"configure"
]
},
"id": {
"type": "string"
},
"config": {
"type": "object"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Action applied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"put": {
"tags": [
"Admin"
],
"summary": "Update environment variables for integrations",
"operationId": "updateIntegrationVars",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"vars"
],
"properties": {
"vars": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Variables updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"updated": {
"type": "array",
"items": {
"type": "string"
}
},
"count": {
"type": "integer"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"delete": {
"tags": [
"Admin"
],
"summary": "Remove environment variables for integrations",
"operationId": "deleteIntegrationVars",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"keys"
],
"properties": {
"keys": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Variables removed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"removed": {
"type": "array",
"items": {
"type": "string"
}
},
"count": {
"type": "integer"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/logs": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Get system logs",
"operationId": "getSystemLogs",
"parameters": [
{
"name": "level",
"in": "query",
"schema": {
"type": "string",
"enum": [
"info",
"warn",
"error",
"debug"
]
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 100
}
}
],
"responses": {
"200": {
"description": "Log entries",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string"
},
"level": {
"type": "string"
},
"message": {
"type": "string"
},
"source": {
"type": "string"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Monitoring"
],
"summary": "Add a custom log entry",
"operationId": "addLogEntry",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action",
"message"
],
"properties": {
"action": {
"type": "string"
},
"message": {
"type": "string"
},
"level": {
"type": "string",
"enum": [
"info",
"warn",
"error",
"debug"
]
},
"source": {
"type": "string"
},
"session": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Log entry added",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"entry": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/memory": {
"get": {
"tags": [
"Admin"
],
"summary": "Get memory files",
"operationId": "getMemoryFiles",
"parameters": [
{
"name": "path",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Memory file contents",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Update memory file",
"operationId": "updateMemoryFile",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"path",
"content"
],
"properties": {
"path": {
"type": "string"
},
"content": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Memory updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"delete": {
"tags": [
"Admin"
],
"summary": "Delete a memory file",
"operationId": "deleteMemoryFile",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action",
"path"
],
"properties": {
"action": {
"type": "string",
"enum": [
"delete"
]
},
"path": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "File deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/mentions": {
"get": {
"tags": [
"Mentions"
],
"summary": "Get mention autocomplete targets",
"operationId": "getMentionTargets",
"parameters": [
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"description": "Search query"
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string",
"enum": [
"user",
"agent"
]
},
"description": "Filter by type"
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
},
"description": "Max results"
}
],
"responses": {
"200": {
"description": "Mention targets list"
}
}
}
},
"/api/notifications": {
"get": {
"tags": [
"Monitoring"
],
"summary": "List notifications",
"operationId": "listNotifications",
"parameters": [
{
"name": "recipient",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "unread",
"in": "query",
"schema": {
"type": "boolean"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 50
}
}
],
"responses": {
"200": {
"description": "Notification list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"notifications": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"recipient": {
"type": "string"
},
"type": {
"type": "string"
},
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"read": {
"type": "boolean"
},
"source_type": {
"type": "string"
},
"source_id": {
"type": "integer"
},
"created_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Monitoring"
],
"summary": "Notification actions (mark read, dismiss)",
"operationId": "notificationAction",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"mark_read",
"mark_all_read",
"dismiss"
]
},
"id": {
"type": "integer"
},
"recipient": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Action applied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"put": {
"tags": [
"Monitoring"
],
"summary": "Mark notifications as read",
"operationId": "markNotificationsRead",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"recipient": {
"type": "string"
},
"markAllRead": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Notifications marked as read",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"markedAsRead": {
"type": "integer"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"delete": {
"tags": [
"Monitoring"
],
"summary": "Delete notifications",
"operationId": "deleteNotifications",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"recipient": {
"type": "string"
},
"olderThan": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Notifications deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"deleted": {
"type": "integer"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/notifications/deliver": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Get notification delivery status and statistics",
"operationId": "getDeliveryStatus",
"parameters": [
{
"name": "agent",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Delivery statistics",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statistics": {
"type": "object"
},
"agents_with_pending": {
"type": "array",
"items": {
"type": "object"
}
},
"recent_deliveries": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Monitoring"
],
"summary": "Deliver notification to agent",
"operationId": "deliverNotification",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"agent",
"title",
"message"
],
"properties": {
"agent": {
"type": "string"
},
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Notification delivered",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/onboarding": {
"get": {
"tags": [
"System"
],
"summary": "Get /api/onboarding",
"operationId": "getApiOnboarding",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"System"
],
"summary": "Post /api/onboarding",
"operationId": "postApiOnboarding",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/pipelines": {
"get": {
"tags": [
"Pipelines"
],
"summary": "List pipelines",
"operationId": "listPipelines",
"responses": {
"200": {
"description": "Pipeline list with enriched step data and run counts",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"pipelines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"template_id": {
"type": "integer"
},
"template_name": {
"type": "string"
},
"on_failure": {
"type": "string",
"enum": [
"stop",
"continue"
]
}
}
}
},
"created_by": {
"type": "string"
},
"use_count": {
"type": "integer"
},
"runs": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"running": {
"type": "integer"
}
}
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Pipelines"
],
"summary": "Create pipeline",
"operationId": "createPipeline",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"steps"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"template_id"
],
"properties": {
"template_id": {
"type": "integer"
},
"on_failure": {
"type": "string",
"enum": [
"stop",
"continue"
],
"default": "stop"
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Pipeline created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"pipeline": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"put": {
"tags": [
"Pipelines"
],
"summary": "Update pipeline",
"operationId": "updatePipeline",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Pipeline updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"pipeline": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"delete": {
"tags": [
"Pipelines"
],
"summary": "Delete pipeline",
"operationId": "deletePipeline",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Pipeline deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/pipelines/run": {
"get": {
"tags": [
"Pipelines"
],
"summary": "List pipeline runs",
"operationId": "listPipelineRuns",
"parameters": [
{
"name": "pipeline_id",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "id",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
}
}
],
"responses": {
"200": {
"description": "Pipeline runs",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"runs": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Pipelines"
],
"summary": "Run a pipeline",
"operationId": "runPipeline",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pipeline_id"
],
"properties": {
"pipeline_id": {
"type": "integer"
},
"params": {
"type": "object"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Pipeline run started",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"run_id": {
"type": "integer"
},
"status": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/pty/attach": {
"get": {
"tags": [
"API"
],
"summary": "List active PTY sessions and tmux sessions",
"operationId": "get_api_pty_attach",
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
}
}
},
"post": {
"tags": [
"API"
],
"summary": "Check PTY support for a session and get WebSocket path",
"operationId": "post_api_pty_attach",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"sessionId",
"kind"
],
"properties": {
"sessionId": {
"type": "string"
},
"kind": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"readonly",
"interactive"
]
}
}
}
}
}
}
}
},
"/api/pty/setup": {
"get": {
"tags": [
"API"
],
"summary": "Check terminal prerequisites (tmux availability)",
"operationId": "get_api_pty_setup",
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
}
}
},
"post": {
"tags": [
"API"
],
"summary": "Install tmux (explicitly confirmed, admin only)",
"operationId": "post_api_pty_setup",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"confirmation"
],
"properties": {
"confirmation": {
"type": "string",
"enum": [
"install_tmux"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"429": {
"description": "Too many installation attempts"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/projects": {
"get": {
"tags": [
"Projects"
],
"summary": "List all projects",
"operationId": "listProjects",
"responses": {
"200": {
"description": "Project list"
}
}
},
"post": {
"tags": [
"Projects"
],
"summary": "Create a new project",
"operationId": "createProject",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Project created"
}
}
}
},
"/api/projects/{id}": {
"get": {
"tags": [
"Projects"
],
"summary": "Get project by ID",
"operationId": "getProject",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Project details"
}
}
},
"patch": {
"tags": [
"Projects"
],
"summary": "Update a project",
"operationId": "updateProject",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated"
}
}
},
"delete": {
"tags": [
"Projects"
],
"summary": "Delete a project",
"operationId": "deleteProject",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Deleted"
}
}
}
},
"/api/projects/{id}/tasks": {
"get": {
"tags": [
"Projects"
],
"summary": "List tasks in a project",
"operationId": "listProjectTasks",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Tasks in project"
}
}
}
},
"/api/quality-review": {
"get": {
"tags": [
"Quality"
],
"summary": "List quality reviews",
"operationId": "listQualityReviews",
"parameters": [
{
"name": "task_id",
"in": "query",
"schema": {
"type": "integer"
},
"description": "Filter by task"
}
],
"responses": {
"200": {
"description": "Quality review list"
}
}
},
"post": {
"tags": [
"Quality"
],
"summary": "Submit a quality review",
"operationId": "submitQualityReview",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"task_id",
"status"
],
"properties": {
"task_id": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"approved",
"rejected"
]
},
"notes": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Review submitted"
}
}
}
},
"/api/releases/check": {
"get": {
"tags": [
"Releases"
],
"summary": "Check for new releases",
"operationId": "checkReleases",
"security": [],
"responses": {
"200": {
"description": "Release info with version comparison"
}
}
}
},
"/api/scheduler": {
"get": {
"tags": [
"Admin"
],
"summary": "Get scheduler status",
"operationId": "getSchedulerStatus",
"responses": {
"200": {
"description": "Scheduler status and registered tasks",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"running": {
"type": "boolean"
},
"tasks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"interval": {
"type": "string"
},
"last_run": {
"type": "integer"
},
"next_run": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Trigger scheduled task",
"operationId": "triggerScheduledTask",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"task"
],
"properties": {
"task": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Task triggered",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"result": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/search": {
"get": {
"tags": [
"Admin"
],
"summary": "Full-text search",
"operationId": "search",
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string",
"enum": [
"tasks",
"agents",
"activities",
"all"
]
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
}
}
],
"responses": {
"200": {
"description": "Search results",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"snippet": {
"type": "string"
},
"score": {
"type": "number"
}
}
}
},
"total": {
"type": "integer"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/sessions": {
"get": {
"tags": [
"Sessions"
],
"summary": "List gateway and local sessions",
"operationId": "listSessions",
"responses": {
"200": {
"description": "Merged gateway and local session list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sessions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"key": {
"type": "string"
},
"agent": {
"type": "string"
},
"model": {
"type": "string"
},
"kind": {
"type": "string"
},
"channel": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"gateway",
"local"
]
},
"active": {
"type": "boolean"
},
"startTime": {
"type": "integer"
},
"lastActivity": {
"type": "integer"
},
"totalTokens": {
"type": "integer"
},
"workingDir": {
"type": [
"string",
"null"
]
},
"userMessages": {
"type": "integer"
},
"assistantMessages": {
"type": "integer"
},
"toolUses": {
"type": "integer"
},
"estimatedCost": {
"type": "number"
},
"lastUserPrompt": {
"type": [
"string",
"null"
]
},
"age": {
"type": "string"
},
"tokens": {
"type": "string"
},
"flags": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"delete": {
"tags": [
"Sessions"
],
"summary": "Delete a session",
"operationId": "deleteApiSessions",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"sessionKey"
],
"properties": {
"sessionKey": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Session deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"sessionKey": {
"type": "string"
},
"result": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Sessions"
],
"summary": "Control session settings",
"operationId": "postApiSessions",
"parameters": [
{
"name": "action",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"set-thinking",
"set-verbose",
"set-reasoning",
"set-label"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"sessionKey"
],
"properties": {
"sessionKey": {
"type": "string"
},
"level": {
"type": "string"
},
"label": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Session control applied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"action": {
"type": "string"
},
"sessionKey": {
"type": "string"
},
"result": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/sessions/continue": {
"post": {
"tags": [
"Sessions"
],
"summary": "Continue a local Claude/Codex/OpenCode session",
"operationId": "postApiSessionsContinue",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"kind",
"id",
"prompt"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"claude-code",
"codex-cli",
"opencode"
]
},
"id": {
"type": "string"
},
"prompt": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Continue result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"reply": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/sessions/transcript": {
"get": {
"tags": [
"Sessions"
],
"summary": "Get transcript snippets for a local session",
"operationId": "getApiSessionsTranscript",
"parameters": [
{
"name": "kind",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"claude-code",
"codex-cli",
"hermes",
"opencode"
]
}
},
{
"name": "id",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 40,
"maximum": 200
}
}
],
"responses": {
"200": {
"description": "Transcript snippets",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": [
"user",
"assistant",
"system"
]
},
"timestamp": {
"type": "string"
},
"parts": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/sessions/transcript/aggregate": {
"get": {
"tags": [
"Sessions"
],
"summary": "Get /api/sessions/transcript/aggregate",
"operationId": "getApiSessionsTranscriptAggregate",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/sessions/transcript/gateway": {
"get": {
"tags": [
"Sessions"
],
"summary": "Get /api/sessions/transcript/gateway",
"operationId": "getApiSessionsTranscriptGateway",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/sessions/{id}/control": {
"post": {
"tags": [
"Sessions"
],
"summary": "Control session (pause/resume/kill)",
"operationId": "controlSession",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"pause",
"resume",
"kill"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Action applied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/settings": {
"get": {
"tags": [
"Admin"
],
"summary": "Get application settings",
"operationId": "getSettings",
"responses": {
"200": {
"description": "Current settings",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"settings": {
"type": "object"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"put": {
"tags": [
"Admin"
],
"summary": "Update settings",
"operationId": "updateSettings",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Settings updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"delete": {
"tags": [
"Admin"
],
"summary": "Reset a setting to default",
"operationId": "resetSetting",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Setting reset"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/skills": {
"delete": {
"tags": [
"Skills"
],
"summary": "Delete a local skill",
"operationId": "deleteApiSkills",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"source",
"name",
"confirmation"
],
"properties": {
"source": {
"type": "string",
"maxLength": 128,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"name": {
"type": "string",
"maxLength": 128,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"confirmation": {
"type": "string",
"enum": [
"delete_skill"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"get": {
"tags": [
"Skills"
],
"summary": "Get /api/skills",
"operationId": "getApiSkills",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Skills"
],
"summary": "Create or replace a local skill",
"operationId": "postApiSkills",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"source",
"name",
"content"
],
"properties": {
"source": {
"type": "string",
"maxLength": 128,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"name": {
"type": "string",
"maxLength": 128,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"content": {
"type": "string",
"maxLength": 262144
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"description": "Skill content failed security checks"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"put": {
"tags": [
"Skills"
],
"summary": "Update a local skill",
"operationId": "putApiSkills",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"source",
"name",
"content"
],
"properties": {
"source": {
"type": "string",
"maxLength": 128,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"name": {
"type": "string",
"maxLength": 128,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"content": {
"type": "string",
"maxLength": 262144
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"description": "Skill content failed security checks"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/skills/registry": {
"get": {
"tags": [
"Skills"
],
"summary": "Get /api/skills/registry",
"operationId": "getApiSkillsRegistry",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Skills"
],
"summary": "Post /api/skills/registry",
"operationId": "postApiSkillsRegistry",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"put": {
"tags": [
"Skills"
],
"summary": "Put /api/skills/registry",
"operationId": "putApiSkillsRegistry",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/spawn": {
"get": {
"tags": [
"Admin"
],
"summary": "Get spawn history",
"operationId": "getSpawnHistory",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 50
}
}
],
"responses": {
"200": {
"description": "Spawn history",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Spawn agent process",
"operationId": "spawnAgent",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"agent"
],
"properties": {
"agent": {
"type": "string"
},
"task": {
"type": "string"
},
"params": {
"type": "object"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Agent spawned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"session_id": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/standup": {
"get": {
"tags": [
"Admin"
],
"summary": "Get standup report",
"operationId": "getStandupReport",
"parameters": [
{
"name": "date",
"in": "query",
"schema": {
"type": "string",
"format": "date"
}
}
],
"responses": {
"200": {
"description": "Standup report",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"agents": {
"type": "array",
"items": {
"type": "object"
}
},
"tasks_completed": {
"type": "integer"
},
"tasks_in_progress": {
"type": "integer"
},
"highlights": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Generate daily standup report",
"operationId": "generateStandupReport",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"agents": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Standup report generated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"standup": {
"type": "object"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/health": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Public health probe",
"description": "Unauthenticated liveness/readiness probe for upstream watchdogs. Returns 200 when the database is reachable, 503 otherwise. Intentionally exposes no row counts, identifiers, or error detail.",
"operationId": "getHealth",
"security": [],
"responses": {
"200": {
"description": "Service healthy (database reachable)",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
},
"db": {
"type": "string",
"enum": [
"ok"
]
},
"ts": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"503": {
"description": "Service degraded (database unreachable)",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"degraded"
]
},
"db": {
"type": "string",
"enum": [
"error"
]
},
"ts": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
}
},
"/api/status": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Get system status",
"operationId": "getSystemStatus",
"security": [],
"responses": {
"200": {
"description": "System health status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ok",
"degraded",
"down"
]
},
"version": {
"type": "string"
},
"uptime": {
"type": "integer"
},
"agents": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"online": {
"type": "integer"
}
}
},
"tasks": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"in_progress": {
"type": "integer"
}
}
}
}
}
}
}
}
}
}
},
"/api/super/provision-jobs": {
"get": {
"tags": [
"Super Admin"
],
"summary": "List provision jobs",
"operationId": "listProvisionJobs",
"responses": {
"200": {
"description": "Provision job list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"tenant_id": {
"type": "integer"
},
"type": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"completed",
"failed"
]
},
"output": {
"type": "string"
},
"created_at": {
"type": "integer"
},
"completed_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Super Admin"
],
"summary": "Create provision job",
"operationId": "createProvisionJob",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tenant_id",
"type"
],
"properties": {
"tenant_id": {
"type": "integer"
},
"type": {
"type": "string"
},
"params": {
"type": "object"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Job created",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/super/provision-jobs/{id}": {
"get": {
"tags": [
"Super Admin"
],
"summary": "Get provision job details",
"operationId": "getProvisionJob",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Job details",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"post": {
"tags": [
"Super Admin"
],
"summary": "Change provision job approval state",
"operationId": "updateProvisionJobState",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"approve",
"reject",
"cancel"
]
},
"reason": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Job state updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/super/provision-jobs/{id}/run": {
"post": {
"tags": [
"Super Admin"
],
"summary": "Run provision job",
"operationId": "runProvisionJob",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Job started",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"status": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/super/tenants": {
"get": {
"tags": [
"Super Admin"
],
"summary": "List tenants",
"operationId": "listTenants",
"responses": {
"200": {
"description": "Tenant list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tenants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"linux_user": {
"type": "string"
},
"created_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Super Admin"
],
"summary": "Create tenant and bootstrap job",
"operationId": "createTenant",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"linux_user": {
"type": "string"
},
"config": {
"type": "object"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Tenant created with bootstrap job",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"description": "Tenant slug or linux user already exists",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/super/tenants/{id}/decommission": {
"post": {
"tags": [
"Super Admin"
],
"summary": "Decommission tenant",
"operationId": "decommissionTenant",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Tenant decommissioned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/tasks": {
"get": {
"tags": [
"Tasks"
],
"summary": "List tasks",
"operationId": "listTasks",
"parameters": [
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"inbox",
"assigned",
"in_progress",
"quality_review",
"done"
]
}
},
{
"name": "assigned_to",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "priority",
"in": "query",
"schema": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
]
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 50,
"maximum": 200
}
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Paginated task list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Tasks"
],
"summary": "Create task",
"operationId": "createTask",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"title"
],
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"inbox",
"assigned",
"in_progress",
"quality_review",
"done"
],
"default": "inbox"
},
"priority": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"default": "medium"
},
"assigned_to": {
"type": "string"
},
"created_by": {
"type": "string"
},
"due_date": {
"type": "string"
},
"estimated_hours": {
"type": "number"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Task created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"description": "Task title already exists",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"put": {
"tags": [
"Tasks"
],
"summary": "Bulk update task statuses",
"operationId": "bulkUpdateTasks",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tasks"
],
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"status"
],
"properties": {
"id": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"inbox",
"assigned",
"in_progress",
"quality_review",
"done"
]
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Tasks updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"updated": {
"type": "integer"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/tasks/queue": {
"get": {
"tags": [
"Tasks"
],
"summary": "Poll next task for an agent",
"operationId": "pollTaskQueue",
"parameters": [
{
"name": "agent",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Agent name. Optional when x-agent-name header is provided."
},
{
"name": "max_capacity",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"default": 1
}
},
{
"name": "x-agent-name",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Agent attribution header used when `agent` query param is omitted."
}
],
"responses": {
"200": {
"description": "Queue poll result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"oneOf": [
{
"$ref": "#/components/schemas/Task"
},
{
"type": "null"
}
]
},
"reason": {
"type": "string",
"enum": [
"continue_current",
"assigned",
"at_capacity",
"no_tasks_available"
]
},
"agent": {
"type": "string"
},
"timestamp": {
"type": "integer"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/tasks/{id}": {
"get": {
"tags": [
"Tasks"
],
"summary": "Get task by ID",
"operationId": "getTask",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Task details",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"put": {
"tags": [
"Tasks"
],
"summary": "Update task",
"operationId": "updateTask",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string"
},
"priority": {
"type": "string"
},
"assigned_to": {
"type": "string"
},
"due_date": {
"type": "string"
},
"estimated_hours": {
"type": "number"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Task updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"tags": [
"Tasks"
],
"summary": "Delete task",
"operationId": "deleteTask",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Task deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/tasks/{id}/broadcast": {
"post": {
"tags": [
"Tasks"
],
"summary": "Broadcast task to agents",
"operationId": "broadcastTask",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agents": {
"type": "array",
"items": {
"type": "string"
}
},
"message": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Task broadcast sent",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"delivered_to": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/tasks/{id}/comments": {
"get": {
"tags": [
"Tasks"
],
"summary": "List task comments",
"operationId": "listTaskComments",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Comment list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"task_id": {
"type": "integer"
},
"author": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"post": {
"tags": [
"Tasks"
],
"summary": "Add comment to task",
"operationId": "addTaskComment",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string"
},
"author": {
"type": "string"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Comment added",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/tokens": {
"get": {
"tags": [
"Tokens"
],
"summary": "Query token usage",
"operationId": "getTokenUsage",
"parameters": [
{
"name": "action",
"in": "query",
"schema": {
"type": "string",
"enum": [
"list",
"stats",
"agent-costs",
"export",
"trends"
],
"default": "list"
}
},
{
"name": "timeframe",
"in": "query",
"schema": {
"type": "string",
"enum": [
"hour",
"day",
"week",
"month",
"all"
],
"default": "all"
}
},
{
"name": "format",
"in": "query",
"description": "Export format (only for action=export)",
"schema": {
"type": "string",
"enum": [
"json",
"csv"
],
"default": "json"
}
}
],
"responses": {
"200": {
"description": "Token usage data. Shape varies by action.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"title": "ListResponse",
"properties": {
"usage": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenUsageRecord"
}
},
"total": {
"type": "integer"
},
"timeframe": {
"type": "string"
}
}
},
{
"type": "object",
"title": "StatsResponse",
"properties": {
"summary": {
"$ref": "#/components/schemas/TokenStats"
},
"models": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/TokenStats"
}
},
"sessions": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/TokenStats"
}
},
"agents": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/TokenStats"
}
},
"timeframe": {
"type": "string"
},
"recordCount": {
"type": "integer"
}
}
},
{
"type": "object",
"title": "TrendsResponse",
"properties": {
"trends": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string"
},
"tokens": {
"type": "integer"
},
"cost": {
"type": "number"
},
"requests": {
"type": "integer"
}
}
}
},
"timeframe": {
"type": "string"
}
}
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Tokens"
],
"summary": "Record token usage",
"operationId": "recordTokenUsage",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"model",
"sessionId",
"inputTokens",
"outputTokens"
],
"properties": {
"model": {
"type": "string"
},
"sessionId": {
"type": "string"
},
"inputTokens": {
"type": "integer"
},
"outputTokens": {
"type": "integer"
},
"operation": {
"type": "string",
"default": "chat_completion"
},
"duration": {
"type": "number"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Usage recorded",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"record": {
"$ref": "#/components/schemas/TokenUsageRecord"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/webhooks": {
"get": {
"tags": [
"Webhooks"
],
"summary": "List webhooks",
"operationId": "listWebhooks",
"responses": {
"200": {
"description": "Webhook list with delivery stats",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"webhooks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Webhook"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Webhooks"
],
"summary": "Create webhook",
"operationId": "createWebhook",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"generate_secret": {
"type": "boolean",
"default": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook created. Secret is only shown in full on creation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"secret": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"put": {
"tags": [
"Webhooks"
],
"summary": "Update webhook",
"operationId": "updateWebhook",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"regenerate_secret": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"secret": {
"type": "string",
"description": "Only present when regenerate_secret is true"
},
"message": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"tags": [
"Webhooks"
],
"summary": "Delete webhook",
"operationId": "deleteWebhook",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"deleted": {
"type": "integer"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/webhooks/deliveries": {
"get": {
"tags": [
"Webhooks"
],
"summary": "Get webhook delivery history",
"operationId": "getWebhookDeliveries",
"parameters": [
{
"name": "webhook_id",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 50
}
}
],
"responses": {
"200": {
"description": "Delivery history",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deliveries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"webhook_id": {
"type": "integer"
},
"event": {
"type": "string"
},
"status_code": {
"type": "integer"
},
"error": {
"type": "string"
},
"created_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/webhooks/retry": {
"post": {
"tags": [
"Webhooks"
],
"summary": "Retry a failed webhook delivery",
"operationId": "retryWebhookDelivery",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"delivery_id"
],
"properties": {
"delivery_id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Delivery retried"
}
}
}
},
"/api/webhooks/test": {
"post": {
"tags": [
"Webhooks"
],
"summary": "Test webhook",
"operationId": "testWebhook",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Test result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"status_code": {
"type": "integer"
},
"response_time_ms": {
"type": "number"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/webhooks/verify-docs": {
"get": {
"tags": [
"Webhooks"
],
"summary": "Get webhook verification documentation",
"operationId": "getWebhookVerifyDocs",
"responses": {
"200": {
"description": "Verification guide and examples"
}
}
}
},
"/api/workflows": {
"get": {
"tags": [
"Workflows"
],
"summary": "List workflow templates",
"operationId": "listWorkflows",
"responses": {
"200": {
"description": "Workflow template list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"templates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
}
},
"created_by": {
"type": "string"
},
"use_count": {
"type": "integer"
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Workflows"
],
"summary": "Create workflow template",
"operationId": "createWorkflow",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"steps"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"agent": {
"type": "string"
},
"action": {
"type": "string"
},
"params": {
"type": "object"
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Template created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"template": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"put": {
"tags": [
"Workflows"
],
"summary": "Update workflow template",
"operationId": "updateWorkflow",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Template updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"template": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"delete": {
"tags": [
"Workflows"
],
"summary": "Delete workflow template",
"operationId": "deleteWorkflow",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Template deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/workload": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Get real-time workload recommendation",
"description": "Returns system workload metrics and an actionable recommendation: `normal`, `throttle`, `shed`, or `pause`. Thresholds are runtime-configurable via `MC_WORKLOAD_*` environment variables.",
"operationId": "getWorkloadSignals",
"responses": {
"200": {
"description": "Workload snapshot and recommendation",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"timestamp": {
"type": "integer"
},
"workspace_id": {
"type": "integer"
},
"capacity": {
"type": "object",
"properties": {
"active_tasks": {
"type": "integer"
},
"tasks_last_5m": {
"type": "integer"
},
"errors_last_5m": {
"type": "integer"
},
"error_rate_5m": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"completions_last_hour": {
"type": "integer"
},
"avg_completion_rate_per_hour": {
"type": "number"
}
}
},
"queue": {
"type": "object",
"properties": {
"total_pending": {
"type": "integer"
},
"by_status": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"by_priority": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"oldest_pending_age_seconds": {
"type": [
"integer",
"null"
]
},
"estimated_wait_seconds": {
"type": [
"integer",
"null"
]
},
"estimated_wait_confidence": {
"type": "string",
"enum": [
"calculated",
"unknown"
]
}
}
},
"agents": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"online": {
"type": "integer"
},
"busy": {
"type": "integer"
},
"idle": {
"type": "integer"
},
"offline": {
"type": "integer"
},
"busy_ratio": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"load_distribution": {
"type": "array",
"items": {
"type": "object",
"properties": {
"agent": {
"type": "string"
},
"assigned": {
"type": "integer"
},
"in_progress": {
"type": "integer"
}
}
}
}
}
},
"recommendation": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"normal",
"throttle",
"shed",
"pause"
]
},
"reason": {
"type": "string"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
},
"submit_ok": {
"type": "boolean"
},
"suggested_delay_ms": {
"type": "integer"
}
}
},
"thresholds": {
"type": "object",
"description": "Effective runtime thresholds after environment overrides."
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/workspaces": {
"get": {
"tags": [
"Projects"
],
"summary": "Get /api/workspaces",
"operationId": "getApiWorkspaces",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Projects"
],
"summary": "Post /api/workspaces",
"operationId": "postApiWorkspaces",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/workspaces/{id}": {
"delete": {
"tags": [
"Projects"
],
"summary": "Delete /api/workspaces/{id}",
"operationId": "deleteApiWorkspacesId",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"get": {
"tags": [
"Projects"
],
"summary": "Get /api/workspaces/{id}",
"operationId": "getApiWorkspacesId",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"put": {
"tags": [
"Projects"
],
"summary": "Put /api/workspaces/{id}",
"operationId": "putApiWorkspacesId",
"responses": {
"200": {
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/agents/{id}/hide": {
"post": {
"tags": [
"API"
],
"summary": "Hide agent",
"operationId": "post_api_agents_id_hide",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
},
"delete": {
"tags": [
"API"
],
"summary": "Unhide agent",
"operationId": "delete_api_agents_id_hide",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
]
}
},
"/api/agents/{id}/keys": {
"get": {
"tags": [
"API"
],
"summary": "List agent API keys",
"operationId": "get_api_agents_id_keys",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
]
},
"post": {
"tags": [
"API"
],
"summary": "Create agent API key",
"operationId": "post_api_agents_id_keys",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
},
"delete": {
"tags": [
"API"
],
"summary": "Revoke agent API key",
"operationId": "delete_api_agents_id_keys",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
]
}
},
"/api/agents/{id}/files": {
"get": {
"tags": [
"API"
],
"summary": "Get agent workspace files",
"operationId": "get_api_agents_id_files",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
]
},
"put": {
"tags": [
"API"
],
"summary": "Update agent workspace file",
"operationId": "put_api_agents_id_files",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
},
"/api/chat/session-prefs": {
"get": {
"tags": [
"API"
],
"summary": "Get chat session preferences",
"operationId": "get_api_chat_session_prefs",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
},
"patch": {
"tags": [
"API"
],
"summary": "Update chat session preference",
"operationId": "patch_api_chat_session_prefs",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
},
"/api/debug": {
"get": {
"tags": [
"API"
],
"summary": "Debug gateway status",
"operationId": "get_api_debug",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
},
"post": {
"tags": [
"API"
],
"summary": "Proxy debug call to gateway",
"operationId": "post_api_debug",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
},
"/api/diagnostics": {
"get": {
"tags": [
"API"
],
"summary": "Get diagnostics report",
"operationId": "get_api_diagnostics",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/docs/content": {
"get": {
"tags": [
"API"
],
"summary": "Get docs content",
"operationId": "get_api_docs_content",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/docs/search": {
"get": {
"tags": [
"API"
],
"summary": "Search docs",
"operationId": "get_api_docs_search",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/docs/tree": {
"get": {
"tags": [
"API"
],
"summary": "Get docs tree",
"operationId": "get_api_docs_tree",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/setup": {
"get": {
"tags": [
"API"
],
"summary": "Get setup status",
"operationId": "get_api_setup",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
},
"post": {
"tags": [
"API"
],
"summary": "Run first-time setup",
"operationId": "post_api_setup",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
},
"/api/openclaw/doctor": {
"get": {
"tags": [
"API"
],
"summary": "Run OpenClaw doctor",
"operationId": "get_api_openclaw_doctor",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
},
"post": {
"tags": [
"API"
],
"summary": "Run OpenClaw doctor fix",
"operationId": "post_api_openclaw_doctor",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"429": {
"description": "Too many maintenance attempts"
},
"500": {
"description": "Internal server error"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"confirmation"
],
"properties": {
"confirmation": {
"type": "string",
"enum": [
"fix_openclaw"
]
}
}
}
}
}
}
}
},
"/api/openclaw/version": {
"get": {
"tags": [
"API"
],
"summary": "Get OpenClaw version info",
"operationId": "get_api_openclaw_version",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/openclaw/update": {
"post": {
"tags": [
"API"
],
"summary": "Update OpenClaw",
"operationId": "post_api_openclaw_update",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"429": {
"description": "Too many maintenance attempts"
},
"500": {
"description": "Internal server error"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"confirmation"
],
"properties": {
"confirmation": {
"type": "string",
"enum": [
"update_openclaw"
]
}
}
}
}
}
}
}
},
"/api/tasks/{id}/branch": {
"get": {
"tags": [
"API"
],
"summary": "Get task branch/PR status",
"operationId": "get_api_tasks_id_branch",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
]
},
"post": {
"tags": [
"API"
],
"summary": "Create task branch/PR",
"operationId": "post_api_tasks_id_branch",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Resource identifier"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
},
"/api/tokens/rotate": {
"get": {
"tags": [
"API"
],
"summary": "Get API key rotation metadata",
"operationId": "get_api_tokens_rotate",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal server error"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Rotate API key",
"operationId": "rotateApiKey",
"responses": {
"200": {
"description": "API key rotated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"masked_key": {
"type": "string"
},
"rotated_at": {
"type": "integer"
},
"rotated_by": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"description": "Rate limited"
}
}
}
},
"/api/tokens/by-agent": {
"get": {
"tags": [
"Tokens"
],
"summary": "Get per-agent token cost breakdown",
"operationId": "getTokensByAgent",
"parameters": [
{
"name": "days",
"in": "query",
"schema": {
"type": "integer",
"default": 30,
"minimum": 1,
"maximum": 365
},
"description": "Time window in days"
}
],
"responses": {
"200": {
"description": "Per-agent cost breakdown",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"agent": {
"type": "string"
},
"total_input_tokens": {
"type": "integer"
},
"total_output_tokens": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"total_cost": {
"type": "number"
},
"session_count": {
"type": "integer"
},
"request_count": {
"type": "integer"
},
"last_active": {
"type": "string",
"format": "date-time"
},
"models": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
},
"summary": {
"type": "object",
"properties": {
"total_cost": {
"type": "number"
},
"total_tokens": {
"type": "integer"
},
"agent_count": {
"type": "integer"
},
"days": {
"type": "integer"
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/agents/register": {
"post": {
"tags": [
"Agents"
],
"summary": "Agent self-registration",
"operationId": "registerAgent",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$"
},
"role": {
"type": "string",
"enum": [
"coder",
"reviewer",
"tester",
"devops",
"researcher",
"assistant",
"agent"
],
"default": "agent"
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"framework": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Agent already exists, status updated"
},
"201": {
"description": "Agent registered",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agent": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"status": {
"type": "string"
},
"created_at": {
"type": "integer"
}
}
},
"registered": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
}
}
},
"400": {
"description": "Invalid input"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"409": {
"description": "Agent name conflict"
},
"429": {
"description": "Rate limited"
}
}
}
},
"/api/tasks/outcomes": {
"get": {
"tags": [
"Tasks"
],
"summary": "Get task outcome analytics",
"operationId": "getTaskOutcomes",
"parameters": [
{
"name": "timeframe",
"in": "query",
"schema": {
"type": "string",
"enum": [
"day",
"week",
"month",
"all"
],
"default": "all"
},
"description": "Time window filter"
}
],
"responses": {
"200": {
"description": "Task outcome summary",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"timeframe": {
"type": "string"
},
"summary": {
"type": "object",
"properties": {
"total_done": {
"type": "integer"
},
"with_outcome": {
"type": "integer"
},
"by_outcome": {
"type": "object"
},
"avg_retry_count": {
"type": "number"
},
"avg_time_to_resolution_seconds": {
"type": "number"
},
"success_rate": {
"type": "number"
}
}
},
"by_agent": {
"type": "object"
},
"by_priority": {
"type": "object"
},
"common_errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"error_message": {
"type": "string"
},
"count": {
"type": "integer"
}
}
}
},
"record_count": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/tasks/regression": {
"get": {
"tags": [
"Tasks"
],
"summary": "Get task regression metrics",
"operationId": "getTaskRegression",
"parameters": [
{
"name": "beta_start",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Cutover timestamp (unix seconds or ISO)"
},
{
"name": "lookback_seconds",
"in": "query",
"schema": {
"type": "integer",
"default": 604800
},
"description": "Baseline window lookback in seconds"
}
],
"responses": {
"200": {
"description": "Regression comparison metrics",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metric_definitions": {
"type": "object"
},
"params": {
"type": "object",
"properties": {
"beta_start": {
"type": "integer"
},
"lookback_seconds": {
"type": "integer"
}
}
},
"windows": {
"type": "object",
"properties": {
"baseline": {
"type": "object"
},
"post": {
"type": "object"
}
}
},
"deltas": {
"type": "object",
"properties": {
"p95_latency_seconds": {
"type": "number",
"nullable": true
},
"intervention_rate": {
"type": "number"
}
}
}
}
}
}
}
},
"400": {
"description": "Missing or invalid beta_start"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"description": "Rate limited"
}
}
}
},
"/api/agents/evals": {
"get": {
"tags": [
"Agents"
],
"summary": "Get agent evaluation results",
"operationId": "getAgentEvals",
"parameters": [
{
"name": "agent",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "action",
"in": "query",
"schema": {
"type": "string",
"enum": [
"history"
]
}
},
{
"name": "weeks",
"in": "query",
"schema": {
"type": "integer",
"default": 4
}
}
],
"responses": {
"200": {
"description": "Eval results",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Agents"
],
"summary": "Run agent evaluations or manage golden sets",
"operationId": "runAgentEvals",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"run",
"golden-set"
]
},
"agent": {
"type": "string"
},
"layer": {
"type": "string"
},
"name": {
"type": "string"
},
"entries": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Eval results or golden set saved",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/agents/optimize": {
"get": {
"tags": [
"Agents"
],
"summary": "Get agent optimization analysis",
"operationId": "getAgentOptimization",
"parameters": [
{
"name": "agent",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hours",
"in": "query",
"schema": {
"type": "integer",
"default": 24
}
}
],
"responses": {
"200": {
"description": "Optimization analysis",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/channels": {
"get": {
"tags": [
"Admin"
],
"summary": "Get channel statuses from gateway",
"operationId": "getChannelStatuses",
"parameters": [
{
"name": "action",
"in": "query",
"schema": {
"type": "string",
"enum": [
"probe"
]
}
},
{
"name": "channel",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Channel statuses",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Perform channel action (link, logout, profile)",
"operationId": "channelAction",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string"
},
"force": {
"type": "boolean"
},
"accountId": {
"type": "string"
},
"profile": {
"type": "object"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Action result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/claude-tasks": {
"get": {
"tags": [
"Tasks"
],
"summary": "Get Claude Code teams and tasks",
"operationId": "getClaudeTasks",
"parameters": [
{
"name": "force",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
}
}
],
"responses": {
"200": {
"description": "Claude Code tasks",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/gateways/discover": {
"get": {
"tags": [
"Admin"
],
"summary": "Discover gateway instances via systemd",
"operationId": "discoverGateways",
"responses": {
"200": {
"description": "Discovered gateways",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"gateways": {
"type": "array",
"items": {
"type": "object",
"properties": {
"user": {
"type": "string"
},
"port": {
"type": "integer"
},
"active": {
"type": "boolean"
},
"description": {
"type": "string"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/gateways/health/history": {
"get": {
"tags": [
"Admin"
],
"summary": "Get gateway health probe history",
"operationId": "getGatewayHealthHistory",
"responses": {
"200": {
"description": "Health history by gateway",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"gatewayId": {
"type": "integer"
},
"name": {
"type": "string",
"nullable": true
},
"entries": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/github/sync": {
"get": {
"tags": [
"Admin"
],
"summary": "Get GitHub sync status for all projects",
"operationId": "getGithubSyncStatus",
"responses": {
"200": {
"description": "Sync status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"syncs": {
"type": "array",
"items": {
"type": "object"
}
},
"poller": {
"type": "object"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Trigger GitHub sync",
"operationId": "triggerGithubSync",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"trigger",
"trigger-all"
]
},
"project_id": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Sync result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/gnap": {
"get": {
"tags": [
"Admin"
],
"summary": "Get GNAP sync status",
"operationId": "getGnapStatus",
"responses": {
"200": {
"description": "GNAP status",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "GNAP management actions (init, sync)",
"operationId": "gnapAction",
"parameters": [
{
"name": "action",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"init",
"sync"
]
}
}
],
"responses": {
"200": {
"description": "Action result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/hermes": {
"get": {
"tags": [
"Admin"
],
"summary": "Get Hermes agent status",
"operationId": "getHermesStatus",
"responses": {
"200": {
"description": "Hermes status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"installed": {
"type": "boolean"
},
"gatewayRunning": {
"type": "boolean"
},
"hookInstalled": {
"type": "boolean"
},
"activeSessions": {
"type": "integer"
},
"cronJobCount": {
"type": "integer"
},
"memoryEntries": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Manage Hermes hook (install, uninstall)",
"operationId": "hermesHookAction",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"install-hook",
"uninstall-hook"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Hook action result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/hermes/events": {
"post": {
"tags": [
"Agents"
],
"summary": "Receive Hermes hook events",
"operationId": "postHermesEvents",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"event"
],
"properties": {
"event": {
"type": "string"
},
"session_id": {
"type": "string"
},
"source": {
"type": "string"
},
"timestamp": {
"type": "string"
},
"agent_name": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Hermes event accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"event": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/hermes/memory": {
"get": {
"tags": [
"Admin"
],
"summary": "Get Hermes memory file contents",
"operationId": "getHermesMemory",
"responses": {
"200": {
"description": "Hermes memory data",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/hermes/tasks": {
"get": {
"tags": [
"Admin"
],
"summary": "Get Hermes cron jobs",
"operationId": "getHermesTasks",
"parameters": [
{
"name": "force",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
}
}
],
"responses": {
"200": {
"description": "Hermes tasks",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/index": {
"get": {
"tags": [
"Docs"
],
"summary": "API endpoint catalog",
"operationId": "getApiIndex",
"responses": {
"200": {
"description": "Endpoint catalog",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"version": {
"type": "string"
},
"total_endpoints": {
"type": "integer"
},
"endpoints": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
}
}
}
},
"/api/local/agents-doc": {
"get": {
"tags": [
"Admin"
],
"summary": "Discover and read local AGENTS.md",
"operationId": "getLocalAgentsDoc",
"responses": {
"200": {
"description": "AGENTS.md content",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"found": {
"type": "boolean"
},
"path": {
"type": "string",
"nullable": true
},
"content": {
"type": "string",
"nullable": true
},
"candidates": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/local/flight-deck": {
"get": {
"tags": [
"Admin"
],
"summary": "Check Flight Deck local installation status",
"operationId": "getFlightDeckStatus",
"responses": {
"200": {
"description": "Installation status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"installed": {
"type": "boolean"
},
"installPath": {
"type": "string",
"nullable": true
},
"appUrl": {
"type": "string"
},
"downloadUrl": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Launch Flight Deck for agent/session",
"operationId": "launchFlightDeck",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agent": {
"type": "string"
},
"session": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Flight Deck launched",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/local/terminal": {
"post": {
"tags": [
"Admin"
],
"summary": "Open a local Terminal window",
"operationId": "openLocalTerminal",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"cwd"
],
"properties": {
"cwd": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Terminal opened",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/memory/context": {
"get": {
"tags": [
"Admin"
],
"summary": "Generate context payload for agent session start",
"operationId": "getMemoryContext",
"responses": {
"200": {
"description": "Context payload",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/memory/graph": {
"get": {
"tags": [
"Admin"
],
"summary": "Get agent memory graph data (RAG vector DB stats)",
"operationId": "getMemoryGraph",
"parameters": [
{
"name": "agent",
"in": "query",
"schema": {
"type": "string",
"default": "all"
}
}
],
"responses": {
"200": {
"description": "Memory graph data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agents": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/memory/health": {
"get": {
"tags": [
"Admin"
],
"summary": "Run memory workspace health diagnostics",
"operationId": "getMemoryHealth",
"responses": {
"200": {
"description": "Health report",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"overall": {
"type": "string"
},
"overallScore": {
"type": "integer"
},
"categories": {
"type": "array",
"items": {
"type": "object"
}
},
"generatedAt": {
"type": "integer"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/memory/links": {
"get": {
"tags": [
"Admin"
],
"summary": "Get wiki-link graph for memory files",
"operationId": "getMemoryLinks",
"parameters": [
{
"name": "file",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Link graph or file links",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/memory/search": {
"get": {
"tags": [
"Admin"
],
"summary": "Search memory files with FTS5",
"operationId": "searchMemory",
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
}
],
"responses": {
"200": {
"description": "Search results",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Memory search maintenance actions",
"operationId": "searchMemoryAction",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"rebuild"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Action result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/memory/process": {
"post": {
"tags": [
"Admin"
],
"summary": "Run memory processing pipeline (reflect, reweave, generate-moc)",
"operationId": "processMemory",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"reflect",
"reweave",
"generate-moc"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Processing result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/nodes": {
"get": {
"tags": [
"Admin"
],
"summary": "List gateway nodes or paired devices",
"operationId": "listNodes",
"parameters": [
{
"name": "action",
"in": "query",
"schema": {
"type": "string",
"enum": [
"list",
"devices"
],
"default": "list"
}
}
],
"responses": {
"200": {
"description": "Nodes or devices",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"tags": [
"Admin"
],
"summary": "Device management actions (approve, reject, rotate-token, revoke-token)",
"operationId": "deviceAction",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"approve",
"reject",
"rotate-token",
"revoke-token"
]
},
"requestId": {
"type": "string"
},
"deviceId": {
"type": "string"
},
"role": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Action result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/projects/{id}/agents": {
"get": {
"tags": [
"Projects"
],
"summary": "List agent assignments for a project",
"operationId": "listProjectAgents",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Agent assignments",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"assignments": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"post": {
"tags": [
"Projects"
],
"summary": "Assign agent to project",
"operationId": "assignProjectAgent",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"agent_name"
],
"properties": {
"agent_name": {
"type": "string"
},
"role": {
"type": "string",
"default": "member"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Agent assigned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"delete": {
"tags": [
"Projects"
],
"summary": "Unassign agent from project",
"operationId": "unassignProjectAgent",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "agent_name",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Agent unassigned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/api/schedule-parse": {
"get": {
"tags": [
"Admin"
],
"summary": "Parse natural language schedule expression to cron",
"operationId": "parseSchedule",
"parameters": [
{
"name": "input",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Parsed schedule",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cronExpr": {
"type": "string"
},
"humanReadable": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
}
}
}
},
"/api/security-audit": {
"get": {
"tags": [
"Admin"
],
"summary": "Get security audit dashboard",
"operationId": "getSecurityAudit",
"parameters": [
{
"name": "timeframe",
"in": "query",
"schema": {
"type": "string",
"enum": [
"hour",
"day",
"week",
"month"
],
"default": "day"
}
},
{
"name": "event_type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "severity",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "agent",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Security audit data",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/security-scan": {
"get": {
"tags": [
"Admin"
],
"summary": "Run infrastructure security scan",
"operationId": "runSecurityScan",
"responses": {
"200": {
"description": "Security scan results",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/security-scan/agent": {
"post": {
"tags": [
"Admin"
],
"summary": "Agent-callable security scan and fix",
"operationId": "agentSecurityScanFix",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"scan",
"fix",
"scan-and-fix"
]
},
"fixScope": {
"type": "string",
"enum": [
"safe",
"safe+restart",
"all"
]
},
"ids": {
"type": "array",
"items": {
"type": "string"
}
},
"force": {
"type": "boolean"
},
"dryRun": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Scan and fix results",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/security-scan/fix": {
"post": {
"tags": [
"Admin"
],
"summary": "Auto-fix security scan issues",
"operationId": "fixSecurityIssues",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Fix results",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/api/super/os-users": {
"get": {
"tags": [
"Super Admin"
],
"summary": "Discover OS-level user accounts",
"operationId": "listOsUsers",
"responses": {
"200": {
"description": "OS users",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"type": "object"
}
},
"platform": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Super Admin"
],
"summary": "Create OS user and register as tenant",
"operationId": "createOsUser",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"username",
"display_name"
],
"additionalProperties": false,
"properties": {
"username": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]{1,30}[a-z0-9]$"
},
"display_name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"password": {
"type": "string",
"minLength": 12,
"maxLength": 128
},
"gateway_mode": {
"type": "boolean"
},
"gateway_port": {
"type": "integer",
"minimum": 1024,
"maximum": 65535
},
"owner_gateway": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"dry_run": {
"type": "boolean"
},
"install_openclaw": {
"type": "boolean"
},
"install_claude": {
"type": "boolean"
},
"install_codex": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"201": {
"description": "User created",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"description": "User already exists"
},
"429": {
"description": "Provisioning rate limit exceeded"
}
}
}
},
"/api/system-monitor": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Get system resource metrics (CPU, memory, disk, GPU, network, processes)",
"operationId": "getSystemMonitor",
"responses": {
"200": {
"description": "System metrics snapshot",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"timestamp": {
"type": "integer"
},
"cpu": {
"type": "object"
},
"memory": {
"type": "object"
},
"disk": {
"type": "array",
"items": {
"type": "object"
}
},
"gpu": {
"type": "array",
"items": {
"type": "object"
},
"nullable": true
},
"network": {
"type": "array",
"items": {
"type": "object"
}
},
"processes": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/auth/google/disconnect": {
"post": {
"tags": [
"Auth"
],
"summary": "Disconnect Google OAuth from account",
"operationId": "disconnectGoogle",
"responses": {
"200": {
"description": "Google disconnected",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/api/releases/update": {
"post": {
"tags": [
"Releases"
],
"summary": "Update Mission Control to a specific version",
"operationId": "updateRelease",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"targetVersion",
"confirmation"
],
"properties": {
"targetVersion": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"confirmation": {
"type": "string",
"enum": [
"update_mission_control"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Update result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"previousVersion": {
"type": "string"
},
"newVersion": {
"type": "string"
},
"tag": {
"type": "string"
},
"restartRequired": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"description": "Release tag not found"
},
"409": {
"description": "Working tree is dirty or release provenance is invalid"
},
"429": {
"description": "Too many update attempts"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
}
},
"components": {
"securitySchemes": {
"sessionCookie": {
"type": "apiKey",
"in": "cookie",
"name": "__Host-mc-session"
},
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "x-api-key"
}
},
"schemas": {
"Error": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"User": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"username": {
"type": "string"
},
"display_name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"admin",
"operator",
"viewer"
]
},
"provider": {
"type": "string"
},
"email": {
"type": "string"
},
"avatar_url": {
"type": "string"
},
"created_at": {
"type": "integer"
},
"last_login_at": {
"type": "integer"
}
}
},
"Agent": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"online",
"offline",
"busy",
"idle",
"error"
]
},
"session_key": {
"type": "string"
},
"soul_content": {
"type": "string"
},
"config": {
"type": "object"
},
"last_seen": {
"type": "integer"
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
},
"taskStats": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"assigned": {
"type": "integer"
},
"in_progress": {
"type": "integer"
},
"completed": {
"type": "integer"
}
}
}
}
},
"Task": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"inbox",
"assigned",
"in_progress",
"quality_review",
"done"
]
},
"priority": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
]
},
"assigned_to": {
"type": "string"
},
"created_by": {
"type": "string"
},
"due_date": {
"type": "string"
},
"estimated_hours": {
"type": "number"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
}
}
},
"TokenUsageRecord": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"model": {
"type": "string"
},
"sessionId": {
"type": "string"
},
"timestamp": {
"type": "integer"
},
"inputTokens": {
"type": "integer"
},
"outputTokens": {
"type": "integer"
},
"totalTokens": {
"type": "integer"
},
"cost": {
"type": "number"
},
"operation": {
"type": "string"
},
"duration": {
"type": "number"
}
}
},
"TokenStats": {
"type": "object",
"properties": {
"totalTokens": {
"type": "integer"
},
"totalCost": {
"type": "number"
},
"requestCount": {
"type": "integer"
},
"avgTokensPerRequest": {
"type": "integer"
},
"avgCostPerRequest": {
"type": "number"
}
}
},
"Webhook": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"secret": {
"type": "string",
"description": "Masked except on creation"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"last_fired_at": {
"type": "integer"
},
"last_status": {
"type": "integer"
},
"total_deliveries": {
"type": "integer"
},
"successful_deliveries": {
"type": "integer"
},
"failed_deliveries": {
"type": "integer"
},
"created_at": {
"type": "integer"
}
}
},
"AlertRule": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entity_type": {
"type": "string",
"enum": [
"agent",
"task",
"session",
"activity"
]
},
"condition_field": {
"type": "string"
},
"condition_operator": {
"type": "string"
},
"condition_value": {
"type": "string"
},
"action_type": {
"type": "string"
},
"action_config": {
"type": "object"
},
"cooldown_minutes": {
"type": "integer"
},
"last_triggered_at": {
"type": "integer"
},
"trigger_count": {
"type": "integer"
},
"created_by": {
"type": "string"
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
}
}
},
"Project": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
}
}
}
},
"responses": {
"BadRequest": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"Unauthorized": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"Forbidden": {
"description": "Insufficient permissions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"NotFound": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"RateLimited": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}