{ "openapi": "3.1.0", "info": { "title": "Agent Swarm API", "version": "1.51.3", "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)." }, "servers": [ { "url": "http://localhost:3013", "description": "Local development" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key via Authorization: Bearer " }, "agentId": { "type": "apiKey", "in": "header", "name": "X-Agent-ID", "description": "Agent UUID for agent-scoped operations" } }, "schemas": {}, "parameters": {} }, "paths": { "/api/active-sessions": { "get": { "summary": "List active sessions", "tags": [ "Active Sessions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "agentId", "in": "query" } ], "responses": { "200": { "description": "Active session list" } } }, "post": { "summary": "Create a new active session", "tags": [ "Active Sessions" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "taskId": { "type": "string" }, "triggerType": { "type": "string", "minLength": 1 }, "inboxMessageId": { "type": "string" }, "taskDescription": { "type": "string" }, "runnerSessionId": { "type": "string" } }, "required": [ "agentId", "triggerType" ] } } } }, "responses": { "201": { "description": "Session created" }, "400": { "description": "Validation error" } } } }, "/api/active-sessions/by-task/{taskId}": { "delete": { "summary": "Delete active session by task ID", "tags": [ "Active Sessions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "taskId", "in": "path" } ], "responses": { "200": { "description": "Session deleted" } } } }, "/api/active-sessions/{id}": { "delete": { "summary": "Delete active session by ID", "tags": [ "Active Sessions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Session deleted" } } } }, "/api/active-sessions/heartbeat/{taskId}": { "put": { "summary": "Update heartbeat for an active session", "tags": [ "Active Sessions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "taskId", "in": "path" } ], "responses": { "200": { "description": "Heartbeat updated" } } } }, "/api/active-sessions/provider-session/{taskId}": { "put": { "summary": "Update provider session ID on an active session", "tags": [ "Active Sessions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "taskId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "providerSessionId": { "type": "string", "minLength": 1 } }, "required": [ "providerSessionId" ] } } } }, "responses": { "200": { "description": "Provider session ID updated" } } } }, "/api/active-sessions/cleanup": { "post": { "summary": "Clean up stale sessions", "tags": [ "Active Sessions" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "maxAgeMinutes": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Cleanup result" } } } }, "/api/agents": { "post": { "summary": "Register or re-register an agent", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "isLead": { "type": "boolean" }, "description": { "type": "string" }, "role": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "maxTasks": { "type": "integer" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Agent re-registered (already existed)" }, "201": { "description": "Agent created" }, "400": { "description": "Validation error" } } }, "get": { "summary": "List all agents", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "tasks" ] }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Agent list with capacity info" } } } }, "/api/agents/{id}/name": { "put": { "summary": "Update agent name", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Agent updated" }, "404": { "description": "Agent not found" }, "409": { "description": "Name conflict" } } } }, "/api/agents/{id}/setup-script": { "get": { "summary": "Fetch agent + global setup scripts for Docker entrypoint", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Setup scripts" }, "404": { "description": "Agent not found" } } } }, "/api/agents/{id}/profile": { "put": { "summary": "Update agent profile (role, description, capabilities, etc.)", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "maxLength": 100 }, "description": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "claudeMd": { "type": "string", "maxLength": 65536 }, "soulMd": { "type": "string", "maxLength": 65536 }, "identityMd": { "type": "string", "maxLength": 65536 }, "setupScript": { "type": "string", "maxLength": 65536 }, "toolsMd": { "type": "string", "maxLength": 65536 }, "changeSource": { "type": "string" }, "changedByAgentId": { "type": "string" }, "changeReason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Profile updated" }, "400": { "description": "Validation error" }, "404": { "description": "Agent not found" } } } }, "/api/agents/{id}/activity": { "put": { "summary": "Update agent last activity timestamp", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Activity updated" } } } }, "/api/agents/{id}": { "get": { "summary": "Get a single agent", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "tasks" ] }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Agent with capacity info" }, "404": { "description": "Agent not found" } } } }, "/api/config/resolved": { "get": { "summary": "Get resolved config (merged global + agent + repo scopes)", "tags": [ "Config" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "agentId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "repoId", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "includeSecrets", "in": "query" } ], "responses": { "200": { "description": "Resolved config entries" } } } }, "/api/config/{id}": { "get": { "summary": "Get a single config entry by ID", "tags": [ "Config" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "includeSecrets", "in": "query" } ], "responses": { "200": { "description": "Config entry" }, "404": { "description": "Config not found" } } }, "delete": { "summary": "Delete a config entry", "tags": [ "Config" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Config deleted" }, "404": { "description": "Config not found" } } } }, "/api/config": { "get": { "summary": "List config entries with optional filters", "tags": [ "Config" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "scopeId", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "includeSecrets", "in": "query" } ], "responses": { "200": { "description": "List of config entries" } } }, "put": { "summary": "Create or update a config entry", "tags": [ "Config" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "global", "agent", "repo" ] }, "scopeId": { "type": [ "string", "null" ] }, "key": { "type": "string", "minLength": 1 }, "value": {}, "isSecret": { "type": "boolean" }, "envPath": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "scope", "key" ] } } } }, "responses": { "200": { "description": "Config entry upserted" }, "400": { "description": "Validation error" } } } }, "/api/db-query": { "post": { "summary": "Execute a read-only SQL query", "tags": [ "Debug" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sql": { "type": "string", "minLength": 1, "maxLength": 10000 }, "params": { "type": "array", "items": {}, "default": [] } }, "required": [ "sql" ] } } } }, "responses": { "200": { "description": "Query results", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": {} } }, "elapsed": { "type": "number" }, "total": { "type": "number" } }, "required": [ "columns", "rows", "elapsed", "total" ] } } } }, "400": { "description": "Invalid or disallowed SQL" } } } }, "/ecosystem": { "get": { "summary": "Get PM2 ecosystem config for agent services", "tags": [ "Ecosystem" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "PM2 ecosystem config" }, "400": { "description": "Missing X-Agent-ID" } } } }, "/api/epics": { "get": { "summary": "List epics with optional filters", "tags": [ "Epics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "leadAgentId", "in": "query" } ], "responses": { "200": { "description": "Epic list with progress" } } }, "post": { "summary": "Create a new epic", "tags": [ "Epics" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "goal": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "leadAgentId": { "type": "string" }, "repoId": { "type": "string" }, "branch": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "goal" ] } } } }, "responses": { "201": { "description": "Epic created" }, "400": { "description": "Validation error" } } } }, "/api/epics/{id}": { "get": { "summary": "Get epic with progress and tasks", "tags": [ "Epics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Epic with tasks" }, "404": { "description": "Epic not found" } } }, "put": { "summary": "Update an epic", "tags": [ "Epics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "responses": { "200": { "description": "Epic updated" }, "404": { "description": "Epic not found" } } }, "delete": { "summary": "Delete an epic", "tags": [ "Epics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Epic deleted" }, "404": { "description": "Epic not found" } } } }, "/api/epics/{id}/tasks": { "post": { "summary": "Add task to epic (create new or assign existing)", "tags": [ "Epics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "task": { "type": "string" }, "agentId": { "type": "string" }, "taskType": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "priority": { "type": "integer" }, "offeredTo": { "type": "string" } } } } } }, "responses": { "200": { "description": "Existing task assigned" }, "201": { "description": "New task created in epic" }, "400": { "description": "Missing task or taskId" }, "404": { "description": "Epic or task not found" } } } }, "/api/channels": { "get": { "summary": "List all channels", "tags": [ "Channels" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Channel list" } } }, "post": { "summary": "Create a new channel", "tags": [ "Channels" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "public", "dm" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Channel created" }, "400": { "description": "Validation error" }, "409": { "description": "Duplicate name" } } } }, "/api/channels/{id}": { "delete": { "summary": "Delete a channel", "tags": [ "Channels" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Channel deleted" }, "400": { "description": "Cannot delete general channel" }, "404": { "description": "Channel not found" } } } }, "/api/channels/{id}/messages": { "get": { "summary": "Get messages in a channel", "tags": [ "Channels" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "before", "in": "query" } ], "responses": { "200": { "description": "Channel messages" }, "404": { "description": "Channel not found" } } }, "post": { "summary": "Post a message to a channel", "tags": [ "Channels" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 }, "agentId": { "type": "string" }, "replyToId": { "type": "string" }, "mentions": { "type": "array", "items": { "type": "string" } } }, "required": [ "content" ] } } } }, "responses": { "201": { "description": "Message posted" }, "400": { "description": "Invalid content or agentId" }, "404": { "description": "Channel not found" } } } }, "/api/channels/{channelId}/messages/{messageId}/thread": { "get": { "summary": "Get thread messages for a message", "tags": [ "Channels" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "channelId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "messageId", "in": "path" } ], "responses": { "200": { "description": "Thread messages" }, "404": { "description": "Channel not found" } } } }, "/api/memory/index": { "post": { "summary": "Ingest content into memory system (async embedding)", "tags": [ "Memory" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "content": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "agent", "swarm" ] }, "source": { "type": "string", "enum": [ "manual", "file_index", "session_summary", "task_completion" ] }, "sourceTaskId": { "type": "string", "format": "uuid" }, "sourcePath": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "content", "name", "scope", "source" ] } } } }, "responses": { "202": { "description": "Content queued for embedding" }, "400": { "description": "Validation error" } } } }, "/api/memory/search": { "post": { "summary": "Search memories by natural language query", "tags": [ "Memory" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Search results" }, "400": { "description": "Missing query or agent ID" } } } }, "/api/prompt-templates/resolved": { "get": { "summary": "Resolve a prompt template for a given event type and scope chain", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "eventType", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agentId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "repoId", "in": "query" } ], "responses": { "200": { "description": "Resolved template info" }, "400": { "description": "Missing eventType" } } } }, "/api/prompt-templates/events": { "get": { "summary": "List all registered event types with their available variables", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of event template definitions" } } } }, "/api/prompt-templates/preview": { "post": { "summary": "Dry-run render a template with provided variables", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "type": "string" }, "body": { "type": "string" }, "variables": { "type": "object", "additionalProperties": {} } }, "required": [ "eventType" ] } } } }, "responses": { "200": { "description": "Rendered template preview" }, "400": { "description": "Validation error" } } } }, "/api/prompt-templates/render": { "post": { "summary": "Full scope-aware template resolution with interpolation (used by workers via HTTP)", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "type": "string" }, "variables": { "type": "object", "additionalProperties": {} }, "agentId": { "type": "string" }, "repoId": { "type": "string" } }, "required": [ "eventType" ] } } } }, "responses": { "200": { "description": "Fully resolved and interpolated template" }, "400": { "description": "Validation error" } } } }, "/api/prompt-templates/{id}/checkout": { "post": { "summary": "Checkout a specific version of a prompt template from history", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "Checked-out template" }, "400": { "description": "Validation error" }, "404": { "description": "Template or version not found" } } } }, "/api/prompt-templates/{id}/reset": { "post": { "summary": "Reset a prompt template to its code-defined default", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Reset template" }, "404": { "description": "Template not found or no code default available" } } } }, "/api/prompt-templates/{id}": { "get": { "summary": "Get a single prompt template with its version history", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Template with history" }, "404": { "description": "Template not found" } } }, "delete": { "summary": "Delete a prompt template override", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Template deleted" }, "400": { "description": "Cannot delete default template" }, "404": { "description": "Template not found" } } } }, "/api/prompt-templates": { "get": { "summary": "List prompt templates with optional filters", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "eventType", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "scopeId", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "isDefault", "in": "query" } ], "responses": { "200": { "description": "List of prompt templates" } } }, "put": { "summary": "Create or update a prompt template override", "tags": [ "PromptTemplates" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "global", "agent", "repo" ] }, "scopeId": { "type": "string" }, "state": { "type": "string", "enum": [ "enabled", "default_prompt_fallback", "skip_event" ] }, "body": { "type": "string" }, "changedBy": { "type": "string" }, "changeReason": { "type": "string" } }, "required": [ "eventType", "body" ] } } } }, "responses": { "200": { "description": "Upserted template" }, "400": { "description": "Validation error" } } } }, "/api/poll": { "get": { "summary": "Poll for triggers (tasks, mentions, epic updates)", "tags": [ "Poll" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Trigger data or null" }, "400": { "description": "Missing X-Agent-ID" }, "404": { "description": "Agent not found" } } } }, "/api/channel-activity/commit-cursors": { "post": { "summary": "Commit channel activity cursors after successful processing", "tags": [ "Poll" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cursorUpdates": { "type": "array", "items": { "type": "object", "properties": { "channelId": { "type": "string" }, "ts": { "type": "string" } }, "required": [ "channelId", "ts" ] } } }, "required": [ "cursorUpdates" ] } } } }, "responses": { "200": { "description": "Cursors committed" }, "400": { "description": "Invalid request" } } } }, "/api/repos/{id}": { "get": { "summary": "Get a repo by ID", "tags": [ "Repos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Repo details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "clonePath": { "type": "string", "minLength": 1 }, "defaultBranch": { "type": "string", "default": "main" }, "autoClone": { "type": "boolean", "default": true }, "createdAt": { "type": "string" }, "lastUpdatedAt": { "type": "string" } }, "required": [ "id", "url", "name", "clonePath", "createdAt", "lastUpdatedAt" ] } } } }, "404": { "description": "Repo not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "put": { "summary": "Update a repo", "tags": [ "Repos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "clonePath": { "type": "string" }, "defaultBranch": { "type": "string" }, "autoClone": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Repo updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "clonePath": { "type": "string", "minLength": 1 }, "defaultBranch": { "type": "string", "default": "main" }, "autoClone": { "type": "boolean", "default": true }, "createdAt": { "type": "string" }, "lastUpdatedAt": { "type": "string" } }, "required": [ "id", "url", "name", "clonePath", "createdAt", "lastUpdatedAt" ] } } } }, "404": { "description": "Repo not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Duplicate repo", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "delete": { "summary": "Delete a repo", "tags": [ "Repos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Repo deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "404": { "description": "Repo not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/repos": { "get": { "summary": "List repos with optional filters", "tags": [ "Repos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "autoClone", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "name", "in": "query" } ], "responses": { "200": { "description": "List of repos", "content": { "application/json": { "schema": { "type": "object", "properties": { "repos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "clonePath": { "type": "string", "minLength": 1 }, "defaultBranch": { "type": "string", "default": "main" }, "autoClone": { "type": "boolean", "default": true }, "createdAt": { "type": "string" }, "lastUpdatedAt": { "type": "string" } }, "required": [ "id", "url", "name", "clonePath", "createdAt", "lastUpdatedAt" ] } } }, "required": [ "repos" ] } } } } } }, "post": { "summary": "Create a new repo", "tags": [ "Repos" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "clonePath": { "type": "string" }, "defaultBranch": { "type": "string" }, "autoClone": { "type": "boolean" } }, "required": [ "url", "name" ] } } } }, "responses": { "201": { "description": "Repo created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "clonePath": { "type": "string", "minLength": 1 }, "defaultBranch": { "type": "string", "default": "main" }, "autoClone": { "type": "boolean", "default": true }, "createdAt": { "type": "string" }, "lastUpdatedAt": { "type": "string" } }, "required": [ "id", "url", "name", "clonePath", "createdAt", "lastUpdatedAt" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Duplicate repo", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/schedules": { "post": { "summary": "Create a new schedule", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "cronExpression": { "type": "string" }, "intervalMs": { "type": "integer" }, "taskTemplate": { "type": "string", "minLength": 1 }, "taskType": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "priority": { "type": "integer" }, "targetAgentId": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "timezone": { "type": "string" }, "model": { "type": "string" }, "scheduleType": { "type": "string", "enum": [ "recurring", "one_time" ] }, "delayMs": { "type": "integer" }, "runAt": { "type": "string" } }, "required": [ "name", "taskTemplate" ] } } } }, "responses": { "201": { "description": "Schedule created" }, "400": { "description": "Validation error" }, "409": { "description": "Duplicate name" } } } }, "/api/schedules/{id}/run": { "post": { "summary": "Run a schedule immediately", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Schedule run triggered" }, "400": { "description": "Schedule is disabled" }, "404": { "description": "Schedule not found" } } } }, "/api/schedules/{id}": { "get": { "summary": "Get a schedule by ID", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Schedule details" }, "404": { "description": "Schedule not found" } } }, "put": { "summary": "Update a schedule", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "cronExpression": { "type": "string" }, "intervalMs": { "type": "integer" }, "taskTemplate": { "type": "string" }, "taskType": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "priority": { "type": "integer" }, "targetAgentId": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "timezone": { "type": "string" }, "model": { "type": "string" }, "nextRunAt": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Schedule updated" }, "400": { "description": "Validation error" }, "404": { "description": "Schedule not found" }, "409": { "description": "Duplicate name" } } }, "delete": { "summary": "Delete a schedule", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Schedule deleted" }, "404": { "description": "Schedule not found" } } } }, "/api/session-logs": { "post": { "summary": "Store session logs", "tags": [ "Session Data" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "iteration": { "type": "integer", "minimum": 1 }, "lines": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "taskId": { "type": "string" }, "cli": { "type": "string" } }, "required": [ "sessionId", "iteration", "lines" ] } } } }, "responses": { "201": { "description": "Logs stored" }, "400": { "description": "Validation error" } } } }, "/api/tasks/{taskId}/session-logs": { "get": { "summary": "Get session logs for a task", "tags": [ "Session Data" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "taskId", "in": "path" } ], "responses": { "200": { "description": "Session logs" }, "404": { "description": "Task not found" } } } }, "/api/session-costs": { "post": { "summary": "Store session cost record", "tags": [ "Session Data" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "totalCostUsd": { "type": "number" }, "taskId": { "type": "string" }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "cacheReadTokens": { "type": "integer" }, "cacheWriteTokens": { "type": "integer" }, "durationMs": { "type": "integer" }, "numTurns": { "type": "integer" }, "model": { "type": "string" }, "isError": { "type": "boolean" } }, "required": [ "sessionId", "agentId", "totalCostUsd" ] } } } }, "responses": { "201": { "description": "Cost record stored" }, "400": { "description": "Validation error" } } }, "get": { "summary": "Query session costs with filters", "tags": [ "Session Data" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "agentId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "taskId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "startDate", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "endDate", "in": "query" }, { "schema": { "type": "integer", "minimum": 1 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Session costs" } } } }, "/api/session-costs/summary": { "get": { "summary": "Aggregated session cost summary", "tags": [ "Session Data" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "day", "agent", "both" ] }, "required": false, "name": "groupBy", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "startDate", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "endDate", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agentId", "in": "query" } ], "responses": { "200": { "description": "Cost summary" }, "400": { "description": "Invalid groupBy" } } } }, "/api/session-costs/dashboard": { "get": { "summary": "Cost today and month-to-date for dashboard", "tags": [ "Session Data" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Dashboard cost data" } } } }, "/api/skills": { "get": { "summary": "List skills with optional filters", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agentId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "enabled", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Skill list" } } }, "post": { "summary": "Create a new skill", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 }, "type": { "type": "string" }, "scope": { "type": "string" }, "ownerAgentId": { "type": "string" } }, "required": [ "content" ] } } } }, "responses": { "201": { "description": "Skill created" }, "400": { "description": "Validation error" } } } }, "/api/skills/{id}": { "get": { "summary": "Get skill by ID", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Skill details" }, "404": { "description": "Skill not found" } } }, "put": { "summary": "Update a skill", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "responses": { "200": { "description": "Skill updated" }, "404": { "description": "Skill not found" } } }, "delete": { "summary": "Delete a skill", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Skill deleted" }, "404": { "description": "Skill not found" } } } }, "/api/skills/{id}/install": { "post": { "summary": "Install skill for an agent", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" } }, "required": [ "agentId" ] } } } }, "responses": { "200": { "description": "Skill installed" }, "404": { "description": "Skill not found" } } } }, "/api/skills/{id}/install/{agentId}": { "delete": { "summary": "Uninstall skill for an agent", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "Skill uninstalled" } } } }, "/api/skills/install-remote": { "post": { "summary": "Install a remote skill from GitHub", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceRepo": { "type": "string" }, "sourcePath": { "type": "string" }, "scope": { "type": "string" }, "isComplex": { "type": "boolean" } }, "required": [ "sourceRepo" ] } } } }, "responses": { "201": { "description": "Remote skill installed" }, "400": { "description": "Fetch failed" } } } }, "/api/skills/sync-remote": { "post": { "summary": "Trigger remote skill sync", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "skillId": { "type": "string" }, "force": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Sync results" } } } }, "/api/skills/sync-filesystem": { "post": { "summary": "Sync installed skills to agent filesystem", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Filesystem sync results" } } } }, "/api/agents/{id}/skills": { "get": { "summary": "Get all skills installed for an agent", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Agent skills list" } } } }, "/api/logs": { "get": { "summary": "List agent logs", "tags": [ "Stats" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "agentId", "in": "query" } ], "responses": { "200": { "description": "Agent logs" } } } }, "/api/stats": { "get": { "summary": "Dashboard summary stats", "tags": [ "Stats" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Agent and task statistics" } } } }, "/api/services": { "get": { "summary": "List all registered services", "tags": [ "Stats" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agentId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "name", "in": "query" } ], "responses": { "200": { "description": "Service list" } } } }, "/api/scheduled-tasks": { "get": { "summary": "List scheduled tasks", "tags": [ "Stats" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "enabled", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "name", "in": "query" }, { "schema": { "type": "string", "enum": [ "recurring", "one_time" ] }, "required": false, "name": "scheduleType", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "hideCompleted", "in": "query" } ], "responses": { "200": { "description": "Scheduled tasks list" } } } }, "/api/concurrent-context": { "get": { "summary": "Get concurrent session context for lead awareness", "tags": [ "Stats" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Concurrent context data" } } } }, "/api/tasks": { "get": { "summary": "List tasks with filters", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agentId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "epicId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "scheduleId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "includeHeartbeat", "in": "query" }, { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Paginated task list" } } }, "post": { "summary": "Create a new task", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "string", "minLength": 1 }, "agentId": { "type": "string" }, "taskType": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "priority": { "type": "integer" }, "dependsOn": { "type": "array", "items": { "type": "string" } }, "offeredTo": { "type": "string" }, "dir": { "type": "string" }, "parentTaskId": { "type": "string" }, "source": { "type": "string" }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "task" ] } } } }, "responses": { "201": { "description": "Task created" }, "400": { "description": "Validation error" } } } }, "/api/tasks/{id}/claude-session": { "put": { "summary": "Update Claude session ID for a task", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "claudeSessionId": { "type": "string", "minLength": 1 } }, "required": [ "claudeSessionId" ] } } } }, "responses": { "200": { "description": "Session ID updated" }, "404": { "description": "Task not found" } } } }, "/api/tasks/{id}/cancel": { "post": { "summary": "Cancel a pending or in-progress task", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Task cancelled" }, "400": { "description": "Cannot cancel terminal task" }, "404": { "description": "Task not found" } } } }, "/api/tasks/{id}": { "get": { "summary": "Get task details with logs", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Task with logs" }, "404": { "description": "Task not found" } } } }, "/api/tasks/{id}/progress": { "post": { "summary": "Update task progress text", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "progress": { "type": "string", "minLength": 1 } }, "required": [ "progress" ] } } } }, "responses": { "200": { "description": "Progress updated" }, "404": { "description": "Task not found" } } } }, "/api/tasks/{id}/finish": { "post": { "summary": "Mark task as completed or failed (runner endpoint)", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "failed" ] }, "output": { "type": "string" }, "failureReason": { "type": "string" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Task finished" }, "400": { "description": "Invalid status" }, "403": { "description": "Not assigned to this agent" }, "404": { "description": "Task not found" } } } }, "/api/paused-tasks": { "get": { "summary": "Get paused tasks for this agent", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Paused task list" } } } }, "/api/tasks/{id}/pause": { "post": { "summary": "Pause an in-progress task", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Task paused" }, "400": { "description": "Task not in_progress" }, "403": { "description": "Task belongs to another agent" }, "404": { "description": "Task not found" } } } }, "/api/tasks/{id}/resume": { "post": { "summary": "Resume a paused task", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Task resumed" }, "400": { "description": "Task not paused" }, "403": { "description": "Task belongs to another agent" }, "404": { "description": "Task not found" } } } }, "/api/trackers/linear/authorize": { "get": { "summary": "Redirect to Linear OAuth consent screen", "tags": [ "Trackers" ], "responses": { "302": { "description": "Redirect to Linear OAuth" }, "500": { "description": "Failed to generate authorization URL" }, "503": { "description": "Linear integration not configured" } } } }, "/api/trackers/linear/callback": { "get": { "summary": "Handle Linear OAuth callback", "tags": [ "Trackers" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": true, "name": "state", "in": "query" } ], "responses": { "200": { "description": "OAuth complete" }, "400": { "description": "Invalid state or code" }, "500": { "description": "Token exchange failed" } } } }, "/api/trackers/linear/status": { "get": { "summary": "Linear connection status, token expiry, workspace info, expected webhook URL", "tags": [ "Trackers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Connection status" }, "503": { "description": "Linear integration not configured" } } } }, "/api/trackers/linear/webhook": { "post": { "summary": "Handle Linear webhook events (signature-verified)", "tags": [ "Trackers" ], "responses": { "200": { "description": "Event accepted" }, "401": { "description": "Invalid signature" }, "503": { "description": "Linear integration not configured" } } } }, "/api/github/webhook": { "post": { "summary": "Handle GitHub webhook events", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Event processed" }, "401": { "description": "Invalid signature" }, "503": { "description": "GitHub integration not configured" } } } }, "/api/gitlab/webhook": { "post": { "summary": "Handle GitLab webhook events", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Event processed" }, "401": { "description": "Invalid token" }, "503": { "description": "GitLab integration not configured" } } } }, "/api/agentmail/webhook": { "post": { "summary": "Handle AgentMail webhook events", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Event received" }, "401": { "description": "Invalid signature" }, "503": { "description": "AgentMail integration not configured" } } } }, "/api/workflows": { "get": { "summary": "List all workflows", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workflow list" } } }, "post": { "summary": "Create a new workflow", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "definition": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique node identifier, used in 'next' and 'inputs' mappings" }, "type": { "type": "string", "description": "Executor type: 'agent-task', 'script', 'raw-llm', 'validate', 'property-match'" }, "label": { "type": "string", "description": "Human-readable label for UI display" }, "config": { "type": "object", "additionalProperties": {}, "description": "Executor-specific config. For agent-task: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }. Values support {{interpolation}} from the node's inputs context. NOTE: config.outputSchema on agent-task nodes validates the AGENT's raw JSON output, while node-level outputSchema validates the EXECUTOR's return value ({taskId, taskOutput})." }, "next": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "string" } } ], "description": "Next node(s): string for simple chaining, string[] for fan-out to parallel nodes, or record for port-based routing ({pass: 'a', fail: 'b'})" }, "validation": { "type": "object", "properties": { "executor": { "type": "string", "default": "validate" }, "config": { "type": "object", "additionalProperties": {} }, "mustPass": { "type": "boolean", "default": false }, "retry": { "type": "object", "properties": { "maxRetries": { "type": "integer", "minimum": 0, "default": 3 }, "strategy": { "type": "string", "enum": [ "exponential", "static", "linear" ], "default": "exponential" }, "baseDelayMs": { "type": "integer", "minimum": 0, "default": 1000 }, "maxDelayMs": { "type": "integer", "minimum": 0, "default": 60000 } } } }, "required": [ "config" ] }, "retry": { "type": "object", "properties": { "maxRetries": { "type": "integer", "minimum": 0, "default": 3 }, "strategy": { "type": "string", "enum": [ "exponential", "static", "linear" ], "default": "exponential" }, "baseDelayMs": { "type": "integer", "minimum": 0, "default": 1000 }, "maxDelayMs": { "type": "integer", "minimum": 0, "default": 60000 } } }, "inputs": { "type": "object", "additionalProperties": { "type": "string" }, "description": "REQUIRED for cross-node data access. Maps local names to context paths. Without this, upstream step outputs are NOT available for interpolation — only 'trigger' and 'input' are. Example: { \"cityData\": \"generate-city\" } → use {{cityData.taskOutput.field}} in config templates. For trigger data: { \"pr\": \"trigger.pullRequest\" }." }, "inputSchema": { "type": "object", "additionalProperties": {}, "description": "JSON Schema to validate resolved inputs before execution" }, "outputSchema": { "type": "object", "additionalProperties": {}, "description": "JSON Schema to validate the executor's output (e.g. {taskId, taskOutput} for agent-task). Different from config.outputSchema which validates the agent's raw output." } }, "required": [ "id", "type", "config" ] }, "minItems": 1 }, "onNodeFailure": { "type": "string", "enum": [ "fail", "continue" ], "default": "fail", "description": "Behavior when a node's task fails or is cancelled. 'fail' (default): mark the entire run as failed. 'continue': treat the failed node as completed with error output and proceed — downstream convergence nodes receive '[FAILED: reason]' and can handle partial results." } }, "required": [ "nodes" ] }, "triggers": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "hmacSecret": { "type": "string" }, "hmacHeader": { "type": "string", "default": "X-Hub-Signature-256" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "schedule" ] }, "scheduleId": { "type": "string", "format": "uuid" } }, "required": [ "type", "scheduleId" ] } ] } }, "cooldown": { "type": "object", "properties": { "hours": { "type": "number", "minimum": 0 }, "minutes": { "type": "number", "minimum": 0 }, "seconds": { "type": "number", "minimum": 0 } } }, "input": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "pattern": "^\\$\\{.+\\}$" }, { "type": "string", "pattern": "^secret\\..+$" }, { "type": "string" } ] } }, "triggerSchema": { "type": "object", "additionalProperties": {} }, "dir": { "type": "string", "minLength": 1 }, "vcsRepo": { "type": "string", "minLength": 1 } }, "required": [ "name", "definition" ] } } } }, "responses": { "201": { "description": "Workflow created" }, "400": { "description": "Invalid definition" } } } }, "/api/workflows/{id}": { "get": { "summary": "Get a workflow by ID", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Workflow details with auto-generated edges" }, "404": { "description": "Workflow not found" } } }, "put": { "summary": "Update a workflow", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "definition": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique node identifier, used in 'next' and 'inputs' mappings" }, "type": { "type": "string", "description": "Executor type: 'agent-task', 'script', 'raw-llm', 'validate', 'property-match'" }, "label": { "type": "string", "description": "Human-readable label for UI display" }, "config": { "type": "object", "additionalProperties": {}, "description": "Executor-specific config. For agent-task: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }. Values support {{interpolation}} from the node's inputs context. NOTE: config.outputSchema on agent-task nodes validates the AGENT's raw JSON output, while node-level outputSchema validates the EXECUTOR's return value ({taskId, taskOutput})." }, "next": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "string" } } ], "description": "Next node(s): string for simple chaining, string[] for fan-out to parallel nodes, or record for port-based routing ({pass: 'a', fail: 'b'})" }, "validation": { "type": "object", "properties": { "executor": { "type": "string", "default": "validate" }, "config": { "type": "object", "additionalProperties": {} }, "mustPass": { "type": "boolean", "default": false }, "retry": { "type": "object", "properties": { "maxRetries": { "type": "integer", "minimum": 0, "default": 3 }, "strategy": { "type": "string", "enum": [ "exponential", "static", "linear" ], "default": "exponential" }, "baseDelayMs": { "type": "integer", "minimum": 0, "default": 1000 }, "maxDelayMs": { "type": "integer", "minimum": 0, "default": 60000 } } } }, "required": [ "config" ] }, "retry": { "type": "object", "properties": { "maxRetries": { "type": "integer", "minimum": 0, "default": 3 }, "strategy": { "type": "string", "enum": [ "exponential", "static", "linear" ], "default": "exponential" }, "baseDelayMs": { "type": "integer", "minimum": 0, "default": 1000 }, "maxDelayMs": { "type": "integer", "minimum": 0, "default": 60000 } } }, "inputs": { "type": "object", "additionalProperties": { "type": "string" }, "description": "REQUIRED for cross-node data access. Maps local names to context paths. Without this, upstream step outputs are NOT available for interpolation — only 'trigger' and 'input' are. Example: { \"cityData\": \"generate-city\" } → use {{cityData.taskOutput.field}} in config templates. For trigger data: { \"pr\": \"trigger.pullRequest\" }." }, "inputSchema": { "type": "object", "additionalProperties": {}, "description": "JSON Schema to validate resolved inputs before execution" }, "outputSchema": { "type": "object", "additionalProperties": {}, "description": "JSON Schema to validate the executor's output (e.g. {taskId, taskOutput} for agent-task). Different from config.outputSchema which validates the agent's raw output." } }, "required": [ "id", "type", "config" ] }, "minItems": 1 }, "onNodeFailure": { "type": "string", "enum": [ "fail", "continue" ], "default": "fail", "description": "Behavior when a node's task fails or is cancelled. 'fail' (default): mark the entire run as failed. 'continue': treat the failed node as completed with error output and proceed — downstream convergence nodes receive '[FAILED: reason]' and can handle partial results." } }, "required": [ "nodes" ] }, "triggers": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "hmacSecret": { "type": "string" }, "hmacHeader": { "type": "string", "default": "X-Hub-Signature-256" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "schedule" ] }, "scheduleId": { "type": "string", "format": "uuid" } }, "required": [ "type", "scheduleId" ] } ] } }, "cooldown": { "type": [ "object", "null" ], "properties": { "hours": { "type": "number", "minimum": 0 }, "minutes": { "type": "number", "minimum": 0 }, "seconds": { "type": "number", "minimum": 0 } } }, "input": { "type": [ "object", "null" ], "additionalProperties": { "anyOf": [ { "type": "string", "pattern": "^\\$\\{.+\\}$" }, { "type": "string", "pattern": "^secret\\..+$" }, { "type": "string" } ] } }, "triggerSchema": { "type": [ "object", "null" ], "additionalProperties": {} }, "dir": { "type": [ "string", "null" ], "minLength": 1 }, "vcsRepo": { "type": [ "string", "null" ], "minLength": 1 }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Workflow updated (version snapshot created)" }, "400": { "description": "Invalid definition" }, "404": { "description": "Workflow not found" } } }, "delete": { "summary": "Delete a workflow", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Workflow deleted" }, "404": { "description": "Workflow not found" } } } }, "/api/workflows/{id}/trigger": { "post": { "summary": "Trigger a workflow execution", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "201": { "description": "Workflow run started (or skipped if cooldown active)" }, "400": { "description": "Workflow is disabled" }, "401": { "description": "Unauthorized" }, "404": { "description": "Workflow not found" } } } }, "/api/workflows/{id}/runs": { "get": { "summary": "List runs for a workflow", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "running", "waiting", "completed", "failed", "skipped" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Workflow run list" } } } }, "/api/workflow-runs/{id}": { "get": { "summary": "Get a workflow run with steps (includes retry columns)", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Workflow run details with steps including retry info" }, "404": { "description": "Run not found" } } } }, "/api/workflow-runs/{id}/retry": { "post": { "summary": "Retry a failed workflow run", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Retry started" }, "400": { "description": "Cannot retry" } } } }, "/api/executor-types": { "get": { "summary": "List all executor types with their config and output schemas", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of executor types with schemas" } } } }, "/api/executor-types/{type}": { "get": { "summary": "Get a specific executor type with its schemas", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "type", "in": "path" } ], "responses": { "200": { "description": "Executor type details" }, "404": { "description": "Executor type not found" } } } }, "/api/webhooks/{workflowId}": { "post": { "summary": "Trigger workflow via webhook", "tags": [ "Webhooks" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "workflowId", "in": "path" } ], "responses": { "201": { "description": "Webhook processed" }, "401": { "description": "Invalid signature" }, "404": { "description": "Workflow not found" } } } }, "/api/workflows/{id}/versions": { "get": { "summary": "List version history for a workflow", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Version list (newest first)" }, "404": { "description": "Workflow not found" } } } }, "/api/workflows/{id}/versions/{version}": { "get": { "summary": "Get a specific version snapshot of a workflow", "tags": [ "Workflows" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1 }, "required": true, "name": "version", "in": "path" } ], "responses": { "200": { "description": "Version snapshot" }, "404": { "description": "Version not found" } } } } }, "webhooks": {} }