{ "openapi": "3.1.0", "info": { "title": "GoodVibes Operator API", "version": "2.0.23", "description": "Generated from the operator contract (packages/contracts/artifacts/operator-contract.json). 507 cataloged methods: 435 with dedicated REST bindings, 72 reachable only through the generic invoke endpoint. 0 methods lack typed SDK client IO and are marked with `x-typed-client-io: false`. They are represented honestly, never omitted. Regenerate with `bun run openapi:generate`; drift fails `contracts:check`." }, "servers": [ { "url": "http://127.0.0.1:{port}", "variables": { "port": { "default": "4483" } }, "description": "Local daemon" } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "paths": { "/api/accounts": { "get": { "operationId": "accounts.snapshot", "summary": "Accounts Snapshot", "description": "Return provider account posture.", "tags": [ "accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "capturedAt": { "type": "number" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "providerId": { "type": "string" }, "active": { "type": "boolean" }, "modelCount": { "type": "number" }, "configured": { "type": "boolean" }, "oauthReady": { "type": "boolean" }, "pendingLogin": { "type": "boolean" }, "availableRoutes": { "type": "array", "items": { "type": "string", "enum": [ "api-key", "subscription", "service-oauth", "unconfigured" ] } }, "preferredRoute": { "type": "string", "enum": [ "api-key", "subscription", "service-oauth", "unconfigured" ] }, "activeRoute": { "type": "string", "enum": [ "api-key", "subscription", "service-oauth", "unconfigured" ] }, "activeRouteReason": { "type": "string" }, "authFreshness": { "type": "string", "enum": [ "healthy", "expiring", "expired", "pending", "unconfigured" ] }, "fallbackRoute": { "type": "string", "enum": [ "api-key", "subscription", "service-oauth", "unconfigured" ] }, "fallbackRisk": { "type": "string" }, "expiresAt": { "type": "number" }, "tokenType": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "usageWindows": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "label", "detail" ], "additionalProperties": false } }, "issues": { "type": "array", "items": { "type": "string" } }, "recommendedActions": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "command": { "type": "object", "properties": { "name": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "args" ], "additionalProperties": false } }, "required": [ "description" ], "additionalProperties": false } }, "routeRecords": { "type": "array", "items": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "api-key", "subscription", "service-oauth", "unconfigured" ] }, "usable": { "type": "boolean" }, "freshness": { "type": "string", "enum": [ "healthy", "expiring", "expired", "pending", "unconfigured" ] }, "detail": { "type": "string" }, "issues": { "type": "array", "items": { "type": "string" } } }, "required": [ "route", "usable", "freshness", "detail", "issues" ], "additionalProperties": false } } }, "required": [ "providerId", "active", "modelCount", "configured", "oauthReady", "pendingLogin", "availableRoutes", "preferredRoute", "activeRoute", "activeRouteReason", "authFreshness", "notes", "usageWindows", "issues", "recommendedActions", "routeRecords" ], "additionalProperties": true } }, "configuredCount": { "type": "number" }, "issueCount": { "type": "number" } }, "required": [ "capturedAt", "providers", "configuredCount", "issueCount" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:accounts" ] } }, "/api/approvals/{approvalId}/approve": { "post": { "operationId": "approvals.approve", "summary": "Approve Approval", "description": "Approve a pending approval. Optionally pass selectedHunks (edit-tool approvals only): the daemon filters the approval's own edit list to those hunk indices server-side, so every surface produces identical modified-edit args. Omitting selectedHunks approves the whole request (back-compat). An out-of-range index or a non-edit approval is rejected with a 400. rememberTier generalizes the decision (a generalizing tier persists a durable rule and sweeps queued asks it covers); modifiedArgs carries an argument-modifying approval, e.g. the typed answer to a command's terminal prompt, to the waiting call (selectedHunks supersedes it when both are present). The response's recorded block reports what the broker actually recorded.", "tags": [ "approvals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string" }, "callId": { "type": "string" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "claimed", "approved", "denied", "cancelled", "expired" ] }, "request": { "type": "object", "properties": { "callId": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "category": { "type": "string", "enum": [ "read", "write", "execute", "delegate" ] }, "analysis": { "type": "object", "properties": { "classification": { "type": "string" }, "riskLevel": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "summary": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "target": { "type": "string" }, "targetKind": { "type": "string", "enum": [ "command", "path", "url", "task", "generic" ] }, "surface": { "type": "string", "enum": [ "filesystem", "shell", "network", "orchestration", "platform", "generic" ] }, "blastRadius": { "type": "string", "enum": [ "local", "project", "external", "delegated", "platform" ] }, "sideEffects": { "type": "array", "items": { "type": "string" } }, "host": { "type": "string" } }, "required": [ "classification", "riskLevel", "summary", "reasons" ], "additionalProperties": false }, "workingDirectory": { "type": "string" }, "attribution": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "background-agent" ] }, "agentId": { "type": "string" }, "template": { "type": "string" } }, "required": [ "kind", "agentId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mcp-server" ] }, "serverName": { "type": "string" } }, "required": [ "kind", "serverName" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sandbox-escalation" ] }, "sandbox": { "type": "string" }, "escalations": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "sandbox", "escalations" ], "additionalProperties": false } ] }, "rememberOptions": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "label": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "tier", "label", "detail" ], "additionalProperties": false } } }, "required": [ "callId", "tool", "args", "category", "analysis" ], "additionalProperties": false }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "claimedBy": { "type": "string" }, "claimedAt": { "type": "number" }, "resolvedAt": { "type": "number" }, "resolvedBy": { "type": "string" }, "decision": { "type": "object", "properties": { "approved": { "type": "boolean" }, "remember": { "type": "boolean" }, "rememberTier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "reason": { "type": "string" }, "modifiedArgs": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "approved" ], "additionalProperties": false }, "fixSessionId": { "type": "string" }, "fixSessionError": { "type": "string" }, "expiresAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "enum": [ "created", "claimed", "approved", "denied", "cancelled", "expired", "updated" ] }, "actor": { "type": "string" }, "actorSurface": { "type": "string" }, "createdAt": { "type": "number" }, "note": { "type": "string" } }, "required": [ "id", "action", "actor", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "callId", "status", "request", "createdAt", "updatedAt", "metadata", "audit" ], "additionalProperties": false }, "recorded": { "type": "object", "properties": { "approved": { "type": "boolean" }, "rememberTier": { "anyOf": [ { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, { "type": "null" } ] }, "reasonStored": { "type": "boolean" }, "modifiedArgsDelivered": { "type": "boolean" } }, "required": [ "approved", "rememberTier", "reasonStored", "modifiedArgsDelivered" ], "additionalProperties": false } }, "required": [ "approval" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvalId": { "type": "string" }, "note": { "type": "string" }, "remember": { "type": "boolean" }, "selectedHunks": { "type": "array", "items": { "type": "number" } }, "rememberTier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "reason": { "type": "string" }, "modifiedArgs": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "approvalId" ], "additionalProperties": false } } } } } }, "/api/approvals/{approvalId}/cancel": { "post": { "operationId": "approvals.cancel", "summary": "Cancel Approval", "description": "Cancel a pending approval.", "tags": [ "approvals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string" }, "callId": { "type": "string" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "claimed", "approved", "denied", "cancelled", "expired" ] }, "request": { "type": "object", "properties": { "callId": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "category": { "type": "string", "enum": [ "read", "write", "execute", "delegate" ] }, "analysis": { "type": "object", "properties": { "classification": { "type": "string" }, "riskLevel": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "summary": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "target": { "type": "string" }, "targetKind": { "type": "string", "enum": [ "command", "path", "url", "task", "generic" ] }, "surface": { "type": "string", "enum": [ "filesystem", "shell", "network", "orchestration", "platform", "generic" ] }, "blastRadius": { "type": "string", "enum": [ "local", "project", "external", "delegated", "platform" ] }, "sideEffects": { "type": "array", "items": { "type": "string" } }, "host": { "type": "string" } }, "required": [ "classification", "riskLevel", "summary", "reasons" ], "additionalProperties": false }, "workingDirectory": { "type": "string" }, "attribution": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "background-agent" ] }, "agentId": { "type": "string" }, "template": { "type": "string" } }, "required": [ "kind", "agentId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mcp-server" ] }, "serverName": { "type": "string" } }, "required": [ "kind", "serverName" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sandbox-escalation" ] }, "sandbox": { "type": "string" }, "escalations": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "sandbox", "escalations" ], "additionalProperties": false } ] }, "rememberOptions": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "label": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "tier", "label", "detail" ], "additionalProperties": false } } }, "required": [ "callId", "tool", "args", "category", "analysis" ], "additionalProperties": false }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "claimedBy": { "type": "string" }, "claimedAt": { "type": "number" }, "resolvedAt": { "type": "number" }, "resolvedBy": { "type": "string" }, "decision": { "type": "object", "properties": { "approved": { "type": "boolean" }, "remember": { "type": "boolean" }, "rememberTier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "reason": { "type": "string" }, "modifiedArgs": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "approved" ], "additionalProperties": false }, "fixSessionId": { "type": "string" }, "fixSessionError": { "type": "string" }, "expiresAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "enum": [ "created", "claimed", "approved", "denied", "cancelled", "expired", "updated" ] }, "actor": { "type": "string" }, "actorSurface": { "type": "string" }, "createdAt": { "type": "number" }, "note": { "type": "string" } }, "required": [ "id", "action", "actor", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "callId", "status", "request", "createdAt", "updatedAt", "metadata", "audit" ], "additionalProperties": false }, "recorded": { "type": "object", "properties": { "approved": { "type": "boolean" }, "rememberTier": { "anyOf": [ { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, { "type": "null" } ] }, "reasonStored": { "type": "boolean" }, "modifiedArgsDelivered": { "type": "boolean" } }, "required": [ "approved", "rememberTier", "reasonStored", "modifiedArgsDelivered" ], "additionalProperties": false } }, "required": [ "approval" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvalId": { "type": "string" }, "note": { "type": "string" }, "remember": { "type": "boolean" } }, "required": [ "approvalId" ], "additionalProperties": false } } } } } }, "/api/approvals/{approvalId}/claim": { "post": { "operationId": "approvals.claim", "summary": "Claim Approval", "description": "Claim a pending approval for operator handling.", "tags": [ "approvals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string" }, "callId": { "type": "string" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "claimed", "approved", "denied", "cancelled", "expired" ] }, "request": { "type": "object", "properties": { "callId": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "category": { "type": "string", "enum": [ "read", "write", "execute", "delegate" ] }, "analysis": { "type": "object", "properties": { "classification": { "type": "string" }, "riskLevel": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "summary": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "target": { "type": "string" }, "targetKind": { "type": "string", "enum": [ "command", "path", "url", "task", "generic" ] }, "surface": { "type": "string", "enum": [ "filesystem", "shell", "network", "orchestration", "platform", "generic" ] }, "blastRadius": { "type": "string", "enum": [ "local", "project", "external", "delegated", "platform" ] }, "sideEffects": { "type": "array", "items": { "type": "string" } }, "host": { "type": "string" } }, "required": [ "classification", "riskLevel", "summary", "reasons" ], "additionalProperties": false }, "workingDirectory": { "type": "string" }, "attribution": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "background-agent" ] }, "agentId": { "type": "string" }, "template": { "type": "string" } }, "required": [ "kind", "agentId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mcp-server" ] }, "serverName": { "type": "string" } }, "required": [ "kind", "serverName" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sandbox-escalation" ] }, "sandbox": { "type": "string" }, "escalations": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "sandbox", "escalations" ], "additionalProperties": false } ] }, "rememberOptions": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "label": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "tier", "label", "detail" ], "additionalProperties": false } } }, "required": [ "callId", "tool", "args", "category", "analysis" ], "additionalProperties": false }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "claimedBy": { "type": "string" }, "claimedAt": { "type": "number" }, "resolvedAt": { "type": "number" }, "resolvedBy": { "type": "string" }, "decision": { "type": "object", "properties": { "approved": { "type": "boolean" }, "remember": { "type": "boolean" }, "rememberTier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "reason": { "type": "string" }, "modifiedArgs": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "approved" ], "additionalProperties": false }, "fixSessionId": { "type": "string" }, "fixSessionError": { "type": "string" }, "expiresAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "enum": [ "created", "claimed", "approved", "denied", "cancelled", "expired", "updated" ] }, "actor": { "type": "string" }, "actorSurface": { "type": "string" }, "createdAt": { "type": "number" }, "note": { "type": "string" } }, "required": [ "id", "action", "actor", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "callId", "status", "request", "createdAt", "updatedAt", "metadata", "audit" ], "additionalProperties": false }, "recorded": { "type": "object", "properties": { "approved": { "type": "boolean" }, "rememberTier": { "anyOf": [ { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, { "type": "null" } ] }, "reasonStored": { "type": "boolean" }, "modifiedArgsDelivered": { "type": "boolean" } }, "required": [ "approved", "rememberTier", "reasonStored", "modifiedArgsDelivered" ], "additionalProperties": false } }, "required": [ "approval" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvalId": { "type": "string" } }, "required": [ "approvalId" ], "additionalProperties": false } } } } } }, "/api/approvals/{approvalId}/deny": { "post": { "operationId": "approvals.deny", "summary": "Deny Approval", "description": "Deny a pending approval. rememberTier generalizes the denial (a generalizing tier persists a durable deny rule and sweeps queued asks it covers); reason is the user's free-text feedback, which rides the structured declined result so the model adapts instead of guessing. The response's recorded block reports what the broker actually recorded.", "tags": [ "approvals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string" }, "callId": { "type": "string" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "claimed", "approved", "denied", "cancelled", "expired" ] }, "request": { "type": "object", "properties": { "callId": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "category": { "type": "string", "enum": [ "read", "write", "execute", "delegate" ] }, "analysis": { "type": "object", "properties": { "classification": { "type": "string" }, "riskLevel": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "summary": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "target": { "type": "string" }, "targetKind": { "type": "string", "enum": [ "command", "path", "url", "task", "generic" ] }, "surface": { "type": "string", "enum": [ "filesystem", "shell", "network", "orchestration", "platform", "generic" ] }, "blastRadius": { "type": "string", "enum": [ "local", "project", "external", "delegated", "platform" ] }, "sideEffects": { "type": "array", "items": { "type": "string" } }, "host": { "type": "string" } }, "required": [ "classification", "riskLevel", "summary", "reasons" ], "additionalProperties": false }, "workingDirectory": { "type": "string" }, "attribution": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "background-agent" ] }, "agentId": { "type": "string" }, "template": { "type": "string" } }, "required": [ "kind", "agentId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mcp-server" ] }, "serverName": { "type": "string" } }, "required": [ "kind", "serverName" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sandbox-escalation" ] }, "sandbox": { "type": "string" }, "escalations": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "sandbox", "escalations" ], "additionalProperties": false } ] }, "rememberOptions": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "label": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "tier", "label", "detail" ], "additionalProperties": false } } }, "required": [ "callId", "tool", "args", "category", "analysis" ], "additionalProperties": false }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "claimedBy": { "type": "string" }, "claimedAt": { "type": "number" }, "resolvedAt": { "type": "number" }, "resolvedBy": { "type": "string" }, "decision": { "type": "object", "properties": { "approved": { "type": "boolean" }, "remember": { "type": "boolean" }, "rememberTier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "reason": { "type": "string" }, "modifiedArgs": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "approved" ], "additionalProperties": false }, "fixSessionId": { "type": "string" }, "fixSessionError": { "type": "string" }, "expiresAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "enum": [ "created", "claimed", "approved", "denied", "cancelled", "expired", "updated" ] }, "actor": { "type": "string" }, "actorSurface": { "type": "string" }, "createdAt": { "type": "number" }, "note": { "type": "string" } }, "required": [ "id", "action", "actor", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "callId", "status", "request", "createdAt", "updatedAt", "metadata", "audit" ], "additionalProperties": false }, "recorded": { "type": "object", "properties": { "approved": { "type": "boolean" }, "rememberTier": { "anyOf": [ { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, { "type": "null" } ] }, "reasonStored": { "type": "boolean" }, "modifiedArgsDelivered": { "type": "boolean" } }, "required": [ "approved", "rememberTier", "reasonStored", "modifiedArgsDelivered" ], "additionalProperties": false } }, "required": [ "approval" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvalId": { "type": "string" }, "note": { "type": "string" }, "remember": { "type": "boolean" }, "rememberTier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "reason": { "type": "string" } }, "required": [ "approvalId" ], "additionalProperties": false } } } } } }, "/api/approvals": { "get": { "operationId": "approvals.list", "summary": "List Approvals", "description": "Return pending and historical approval records.", "tags": [ "approvals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "awaitingDecision": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "default", "plan", "allow-all", "custom", "background-restricted" ] }, "lastDecision": { "type": "object", "properties": { "callId": { "type": "string" }, "toolName": { "type": "string" }, "category": { "type": "string", "enum": [ "read", "write", "execute", "delegate" ] }, "machineState": { "type": "string", "enum": [ "collect_rules", "normalize_input", "evaluate_policy", "evaluate_runtime_mode", "evaluate_session_override", "final_safety_checks", "decision_emitted" ] }, "outcome": { "type": "string", "enum": [ "approved", "denied", "deferred" ] }, "reason": { "type": "string", "enum": [ "config_allow", "config_deny", "managed_policy_allow", "managed_policy_deny", "mode_allow_all", "mode_denied", "mode_plan_deny", "mode_background_restricted", "session_cached_approval", "session_cached_denial", "safety_guardrail", "user_rule_allow", "user_rule_deny", "user_approved", "user_denied" ] }, "sourceLayer": { "type": "string", "enum": [ "config_policy", "managed_policy", "runtime_mode", "session_override", "safety_check", "user_rule", "user_prompt" ] }, "persisted": { "type": "boolean" }, "classification": { "type": "string" }, "riskLevel": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "summary": { "type": "string" }, "decidedAt": { "type": "number" } }, "required": [ "callId", "toolName", "category", "machineState", "outcome", "reason", "sourceLayer", "persisted", "decidedAt" ], "additionalProperties": false }, "approvalCount": { "type": "number" }, "denialCount": { "type": "number" }, "cachedChecks": { "type": "number" }, "totalChecks": { "type": "number" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "callId": { "type": "string" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "claimed", "approved", "denied", "cancelled", "expired" ] }, "request": { "type": "object", "properties": { "callId": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "category": { "type": "string", "enum": [ "read", "write", "execute", "delegate" ] }, "analysis": { "type": "object", "properties": { "classification": { "type": "string" }, "riskLevel": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "summary": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "target": { "type": "string" }, "targetKind": { "type": "string", "enum": [ "command", "path", "url", "task", "generic" ] }, "surface": { "type": "string", "enum": [ "filesystem", "shell", "network", "orchestration", "platform", "generic" ] }, "blastRadius": { "type": "string", "enum": [ "local", "project", "external", "delegated", "platform" ] }, "sideEffects": { "type": "array", "items": { "type": "string" } }, "host": { "type": "string" } }, "required": [ "classification", "riskLevel", "summary", "reasons" ], "additionalProperties": false }, "workingDirectory": { "type": "string" }, "attribution": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "background-agent" ] }, "agentId": { "type": "string" }, "template": { "type": "string" } }, "required": [ "kind", "agentId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mcp-server" ] }, "serverName": { "type": "string" } }, "required": [ "kind", "serverName" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sandbox-escalation" ] }, "sandbox": { "type": "string" }, "escalations": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "sandbox", "escalations" ], "additionalProperties": false } ] }, "rememberOptions": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "label": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "tier", "label", "detail" ], "additionalProperties": false } } }, "required": [ "callId", "tool", "args", "category", "analysis" ], "additionalProperties": false }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "claimedBy": { "type": "string" }, "claimedAt": { "type": "number" }, "resolvedAt": { "type": "number" }, "resolvedBy": { "type": "string" }, "decision": { "type": "object", "properties": { "approved": { "type": "boolean" }, "remember": { "type": "boolean" }, "rememberTier": { "type": "string", "enum": [ "session", "exact", "command-class", "path", "tool" ] }, "reason": { "type": "string" }, "modifiedArgs": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "approved" ], "additionalProperties": false }, "fixSessionId": { "type": "string" }, "fixSessionError": { "type": "string" }, "expiresAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "enum": [ "created", "claimed", "approved", "denied", "cancelled", "expired", "updated" ] }, "actor": { "type": "string" }, "actorSurface": { "type": "string" }, "createdAt": { "type": "number" }, "note": { "type": "string" } }, "required": [ "id", "action", "actor", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "callId", "status", "request", "createdAt", "updatedAt", "metadata", "audit" ], "additionalProperties": false } } }, "required": [ "awaitingDecision", "mode", "approvalCount", "denialCount", "cachedChecks", "totalChecks", "approvals" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:approvals" ] } }, "/api/artifacts/{artifactId}/content": { "get": { "operationId": "artifacts.content.get", "summary": "Get Artifact Content", "description": "Return the raw content bytes for a stored artifact.", "tags": [ "artifacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contentType": { "type": "string" }, "contentLength": { "type": "number" } }, "required": [ "contentType", "contentLength" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http" ], "x-scopes": [ "read:artifacts" ], "parameters": [ { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "download", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/artifacts": { "post": { "operationId": "artifacts.create", "summary": "Create Artifact", "description": "Store a file or attachment artifact for later delivery, analysis, or knowledge ingest. JSON supports small inline bodies and daemon-local path/URI references; HTTP callers can also send multipart/form-data or a raw binary body for large uploads.", "tags": [ "artifacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true } }, "required": [ "artifact" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:artifacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "dataBase64": { "type": "string" }, "text": { "type": "string" }, "path": { "type": "string" }, "uri": { "type": "string" }, "allowPrivateHosts": { "type": "boolean" }, "retentionMs": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "dataBase64": { "type": "string" } }, "required": [ "dataBase64" ], "additionalProperties": true }, { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": true }, { "type": "object", "properties": { "path": { "type": "string" } }, "required": [ "path" ], "additionalProperties": true }, { "type": "object", "properties": { "uri": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": true } ] } } } } }, "get": { "operationId": "artifacts.list", "summary": "List Artifacts", "description": "Return stored artifact metadata for files and attachments.", "tags": [ "artifacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true } } }, "required": [ "artifacts" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:artifacts" ] } }, "/api/artifacts/{artifactId}": { "get": { "operationId": "artifacts.get", "summary": "Get Artifact", "description": "Return metadata for a stored artifact.", "tags": [ "artifacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true } }, "required": [ "artifact" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:artifacts" ], "parameters": [ { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/local-auth/bootstrap-file": { "delete": { "operationId": "local_auth.bootstrap.delete", "summary": "Delete Bootstrap File", "description": "Delete the local-auth bootstrap credential file.", "tags": [ "auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:auth" ], "x-dangerous": true } }, "/api/local-auth/sessions/{sessionId}": { "delete": { "operationId": "local_auth.sessions.delete", "summary": "Revoke Local Auth Session", "description": "Revoke a local auth session.", "tags": [ "auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:auth" ], "x-dangerous": true, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/local-auth": { "get": { "operationId": "local_auth.status", "summary": "Local Auth Status", "description": "Return local auth posture, users, and sessions.", "tags": [ "auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "userStorePath": { "type": "string" }, "bootstrapCredentialPath": { "type": "string" }, "bootstrapCredentialPresent": { "type": "boolean" }, "userCount": { "type": "number" }, "sessionCount": { "type": "number" }, "users": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "username", "roles" ], "additionalProperties": false } }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "tokenFingerprint": { "type": "string" }, "username": { "type": "string" }, "expiresAt": { "type": "number" } }, "required": [ "tokenFingerprint", "username", "expiresAt" ], "additionalProperties": false } } }, "required": [ "userStorePath", "bootstrapCredentialPath", "bootstrapCredentialPresent", "userCount", "sessionCount", "users", "sessions" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:auth" ] } }, "/api/local-auth/users": { "post": { "operationId": "local_auth.users.create", "summary": "Create Local Auth User", "description": "Create a local auth user.", "tags": [ "auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "username": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "username", "roles" ], "additionalProperties": false } }, "required": [ "user" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "username", "password" ], "additionalProperties": true } } } } } }, "/api/local-auth/users/{username}": { "delete": { "operationId": "local_auth.users.delete", "summary": "Delete Local Auth User", "description": "Delete a local auth user.", "tags": [ "auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:auth" ], "x-dangerous": true, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/local-auth/users/{username}/password": { "post": { "operationId": "local_auth.users.password.rotate", "summary": "Rotate Local Auth Password", "description": "Rotate a local auth user password.", "tags": [ "auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rotated": { "type": "boolean" } }, "required": [ "rotated" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:auth" ], "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" } }, "required": [ "password" ], "additionalProperties": true } } } } } }, "/api/automation/heartbeat": { "get": { "operationId": "automation.heartbeat.list", "summary": "List Automation Heartbeat Queue", "description": "Return automation jobs queued for the next heartbeat.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "string" }, "jobName": { "type": "string" }, "trigger": { "type": "string", "enum": [ "scheduled", "manual", "catch_up", "webhook", "surface", "watcher" ] }, "dueRun": { "type": "boolean" }, "attempt": { "type": "number" }, "queuedAt": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "jobId", "jobName", "trigger", "dueRun", "attempt", "queuedAt", "reason" ], "additionalProperties": false } } }, "required": [ "pending" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:automation" ] }, "post": { "operationId": "automation.heartbeat.run", "summary": "Run Automation Heartbeat", "description": "Process automation jobs queued for the next heartbeat.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "processed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "missed" ] }, "agentId": { "type": "string" }, "triggeredBy": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "scheduleKind": { "type": "string", "enum": [ "at", "every", "cron" ] }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "durationMs": { "type": "number" }, "forceRun": { "type": "boolean" }, "dueRun": { "type": "boolean" }, "attempt": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "route": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "continuationMode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "executionIntent": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "targetKind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] } }, "required": [ "mode", "targetKind" ], "additionalProperties": false }, "deliveryIds": { "type": "array", "items": { "type": "string" } }, "deliveryAttempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "jobId": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "dead_lettered" ] }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" }, "responseId": { "type": "string" } }, "required": [ "id", "runId", "jobId", "target", "status" ], "additionalProperties": true } }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "cancelledReason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "jobId", "labels", "createdAt", "updatedAt", "status", "triggeredBy", "target", "execution", "queuedAt", "forceRun", "dueRun", "attempt", "deliveryIds" ], "additionalProperties": true } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "jobId", "error" ], "additionalProperties": false } }, "pending": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "string" }, "jobName": { "type": "string" }, "trigger": { "type": "string", "enum": [ "scheduled", "manual", "catch_up", "webhook", "surface", "watcher" ] }, "dueRun": { "type": "boolean" }, "attempt": { "type": "number" }, "queuedAt": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "jobId", "jobName", "trigger", "dueRun", "attempt", "queuedAt", "reason" ], "additionalProperties": false } }, "checkedAt": { "type": "number" } }, "required": [ "processed", "failed", "pending", "checkedAt" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/automation": { "get": { "operationId": "automation.integration.snapshot", "summary": "Automation Integration Snapshot", "description": "Return the automation integration snapshot.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "jobs": { "type": "number" }, "enabled": { "type": "number" }, "paused": { "type": "number" }, "runs": { "type": "number" } }, "required": [ "jobs", "enabled", "paused", "runs" ], "additionalProperties": false }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "enabled", "paused", "error", "archived" ] }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "nextRunAt": { "type": "number" }, "lastRunAt": { "type": "number" }, "runCount": { "type": "number" }, "failureCount": { "type": "number" } }, "required": [ "id", "name", "enabled", "status", "schedule", "runCount", "failureCount" ], "additionalProperties": true } }, "recentRuns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "status": { "type": "string" }, "trigger": { "type": "string" }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "agentId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "jobId", "status", "trigger", "queuedAt" ], "additionalProperties": true } } }, "required": [ "totals", "jobs", "recentRuns" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:automation" ] } }, "/api/automation/jobs": { "post": { "operationId": "automation.jobs.create", "summary": "Create Automation Job", "description": "Create a durable automation job.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "enabled", "paused", "error", "archived" ] }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "fallbackTargets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "includeSummary": { "type": "boolean" }, "includeTranscript": { "type": "boolean" }, "includeLinks": { "type": "boolean" }, "replyToRouteId": { "type": "string" } }, "required": [ "mode", "targets", "fallbackTargets", "includeSummary", "includeTranscript", "includeLinks" ], "additionalProperties": false }, "failure": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "retry", "cooldown", "disable", "dead_letter" ] }, "maxConsecutiveFailures": { "type": "number" }, "cooldownMs": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "delayMs": { "type": "number" }, "strategy": { "type": "string", "enum": [ "fixed", "linear", "exponential" ] }, "maxDelayMs": { "type": "number" }, "jitterMs": { "type": "number" } }, "required": [ "maxAttempts", "delayMs", "strategy" ], "additionalProperties": false }, "deadLetterRouteId": { "type": "string" }, "disableAfterFailures": { "type": "boolean" }, "notifyRouteId": { "type": "string" } }, "required": [ "action", "maxConsecutiveFailures", "cooldownMs", "retryPolicy" ], "additionalProperties": false }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "nextRunAt": { "type": "number" }, "lastRunAt": { "type": "number" }, "lastRunId": { "type": "string" }, "runCount": { "type": "number" }, "successCount": { "type": "number" }, "failureCount": { "type": "number" }, "pausedReason": { "type": "string" }, "deleteAfterRun": { "type": "boolean" }, "archivedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "labels", "createdAt", "updatedAt", "status", "enabled", "schedule", "execution", "delivery", "failure", "source", "runCount", "successCount", "failureCount", "deleteAfterRun" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prompt": { "type": "string" }, "cron": { "type": "string" }, "every": { "type": "string" }, "at": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" }, "model": { "type": "string" }, "provider": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "reasoningEffort": { "type": "string" }, "thinking": { "type": "string" }, "wakeMode": { "type": "string" }, "timeoutMs": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "type": "string" }, "lightContext": { "type": "boolean" }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "fallbackTargets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "includeSummary": { "type": "boolean" }, "includeTranscript": { "type": "boolean" }, "includeLinks": { "type": "boolean" }, "replyToRouteId": { "type": "string" } }, "required": [ "mode", "targets", "fallbackTargets", "includeSummary", "includeTranscript", "includeLinks" ], "additionalProperties": false }, "failure": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "retry", "cooldown", "disable", "dead_letter" ] }, "maxConsecutiveFailures": { "type": "number" }, "cooldownMs": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "delayMs": { "type": "number" }, "strategy": { "type": "string", "enum": [ "fixed", "linear", "exponential" ] }, "maxDelayMs": { "type": "number" }, "jitterMs": { "type": "number" } }, "required": [ "maxAttempts", "delayMs", "strategy" ], "additionalProperties": false }, "deadLetterRouteId": { "type": "string" }, "disableAfterFailures": { "type": "boolean" }, "notifyRouteId": { "type": "string" } }, "required": [ "action", "maxConsecutiveFailures", "cooldownMs", "retryPolicy" ], "additionalProperties": false }, "enabled": { "type": "boolean" }, "deleteAfterRun": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "kind": { "type": "string", "enum": [ "cron", "every", "at" ] }, "schedule": { "type": "object", "properties": { "expression": { "type": "string" } }, "required": [ "expression" ], "additionalProperties": false } }, "required": [ "prompt" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "cron": { "type": "string" } }, "required": [ "cron" ], "additionalProperties": true }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "schedule": { "type": "object", "properties": { "expression": { "type": "string" } }, "required": [ "expression" ], "additionalProperties": false } }, "required": [ "schedule" ], "additionalProperties": true }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "every": { "type": "string" } }, "required": [ "every" ], "additionalProperties": true }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "string" } }, "required": [ "at" ], "additionalProperties": true } ] } } } } }, "get": { "operationId": "automation.jobs.list", "summary": "List Automation Jobs", "description": "Return automation jobs and recent runs. Without ?limit/?cursor returns { jobs: [...] } (backward compatible). With ?limit=N (1–500, default 100) and optional ?cursor= returns a PaginatedResponse envelope { items, hasMore, nextCursor? }. Invalid cursors return HTTP 400.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "enabled", "paused", "error", "archived" ] }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "fallbackTargets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "includeSummary": { "type": "boolean" }, "includeTranscript": { "type": "boolean" }, "includeLinks": { "type": "boolean" }, "replyToRouteId": { "type": "string" } }, "required": [ "mode", "targets", "fallbackTargets", "includeSummary", "includeTranscript", "includeLinks" ], "additionalProperties": false }, "failure": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "retry", "cooldown", "disable", "dead_letter" ] }, "maxConsecutiveFailures": { "type": "number" }, "cooldownMs": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "delayMs": { "type": "number" }, "strategy": { "type": "string", "enum": [ "fixed", "linear", "exponential" ] }, "maxDelayMs": { "type": "number" }, "jitterMs": { "type": "number" } }, "required": [ "maxAttempts", "delayMs", "strategy" ], "additionalProperties": false }, "deadLetterRouteId": { "type": "string" }, "disableAfterFailures": { "type": "boolean" }, "notifyRouteId": { "type": "string" } }, "required": [ "action", "maxConsecutiveFailures", "cooldownMs", "retryPolicy" ], "additionalProperties": false }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "nextRunAt": { "type": "number" }, "lastRunAt": { "type": "number" }, "lastRunId": { "type": "string" }, "runCount": { "type": "number" }, "successCount": { "type": "number" }, "failureCount": { "type": "number" }, "pausedReason": { "type": "string" }, "deleteAfterRun": { "type": "boolean" }, "archivedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "labels", "createdAt", "updatedAt", "status", "enabled", "schedule", "execution", "delivery", "failure", "source", "runCount", "successCount", "failureCount", "deleteAfterRun" ], "additionalProperties": true } }, "emptyState": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" } }, "required": [ "title", "body" ], "additionalProperties": false } }, "required": [ "jobs" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:automation" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/automation/jobs/{jobId}": { "delete": { "operationId": "automation.jobs.delete", "summary": "Delete Automation Job", "description": "Delete a durable automation job.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "removed" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "x-dangerous": true, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "automation.jobs.update", "summary": "Update Automation Job", "description": "Update a durable automation job. (Renamed from automation.jobs.patch in the 1.0.0 core-verb rename, canonical verb is update, not patch.)", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "enabled", "paused", "error", "archived" ] }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "fallbackTargets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "includeSummary": { "type": "boolean" }, "includeTranscript": { "type": "boolean" }, "includeLinks": { "type": "boolean" }, "replyToRouteId": { "type": "string" } }, "required": [ "mode", "targets", "fallbackTargets", "includeSummary", "includeTranscript", "includeLinks" ], "additionalProperties": false }, "failure": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "retry", "cooldown", "disable", "dead_letter" ] }, "maxConsecutiveFailures": { "type": "number" }, "cooldownMs": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "delayMs": { "type": "number" }, "strategy": { "type": "string", "enum": [ "fixed", "linear", "exponential" ] }, "maxDelayMs": { "type": "number" }, "jitterMs": { "type": "number" } }, "required": [ "maxAttempts", "delayMs", "strategy" ], "additionalProperties": false }, "deadLetterRouteId": { "type": "string" }, "disableAfterFailures": { "type": "boolean" }, "notifyRouteId": { "type": "string" } }, "required": [ "action", "maxConsecutiveFailures", "cooldownMs", "retryPolicy" ], "additionalProperties": false }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "nextRunAt": { "type": "number" }, "lastRunAt": { "type": "number" }, "lastRunId": { "type": "string" }, "runCount": { "type": "number" }, "successCount": { "type": "number" }, "failureCount": { "type": "number" }, "pausedReason": { "type": "string" }, "deleteAfterRun": { "type": "boolean" }, "archivedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "labels", "createdAt", "updatedAt", "status", "enabled", "schedule", "execution", "delivery", "failure", "source", "runCount", "successCount", "failureCount", "deleteAfterRun" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prompt": { "type": "string" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "model": { "type": "string" }, "provider": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "reasoningEffort": { "type": "string" }, "thinking": { "type": "string" }, "wakeMode": { "type": "string" }, "timeoutMs": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "type": "string" }, "lightContext": { "type": "boolean" }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "fallbackTargets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "includeSummary": { "type": "boolean" }, "includeTranscript": { "type": "boolean" }, "includeLinks": { "type": "boolean" }, "replyToRouteId": { "type": "string" } }, "required": [ "mode", "targets", "fallbackTargets", "includeSummary", "includeTranscript", "includeLinks" ], "additionalProperties": false }, "failure": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "retry", "cooldown", "disable", "dead_letter" ] }, "maxConsecutiveFailures": { "type": "number" }, "cooldownMs": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "delayMs": { "type": "number" }, "strategy": { "type": "string", "enum": [ "fixed", "linear", "exponential" ] }, "maxDelayMs": { "type": "number" }, "jitterMs": { "type": "number" } }, "required": [ "maxAttempts", "delayMs", "strategy" ], "additionalProperties": false }, "deadLetterRouteId": { "type": "string" }, "disableAfterFailures": { "type": "boolean" }, "notifyRouteId": { "type": "string" } }, "required": [ "action", "maxConsecutiveFailures", "cooldownMs", "retryPolicy" ], "additionalProperties": false }, "enabled": { "type": "boolean" }, "deleteAfterRun": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/automation/jobs/{jobId}/disable": { "post": { "operationId": "automation.jobs.disable", "summary": "Disable Automation Job", "description": "Disable a durable automation job.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" } }, "required": [ "jobId" ], "additionalProperties": false } } } } } }, "/api/automation/jobs/{jobId}/enable": { "post": { "operationId": "automation.jobs.enable", "summary": "Enable Automation Job", "description": "Enable a durable automation job.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" } }, "required": [ "jobId" ], "additionalProperties": false } } } } } }, "/api/automation/jobs/{jobId}/run": { "post": { "operationId": "automation.jobs.run", "summary": "Run Automation Job Now", "description": "Trigger an automation job immediately.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "runId": { "type": "string" }, "agentId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "jobId", "runId", "status" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" } }, "required": [ "jobId" ], "additionalProperties": false } } } } } }, "/api/automation/runs/{runId}/cancel": { "post": { "operationId": "automation.runs.cancel", "summary": "Cancel Automation Run", "description": "Cancel an active automation run.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "missed" ] }, "agentId": { "type": "string" }, "triggeredBy": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "scheduleKind": { "type": "string", "enum": [ "at", "every", "cron" ] }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "durationMs": { "type": "number" }, "forceRun": { "type": "boolean" }, "dueRun": { "type": "boolean" }, "attempt": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "route": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "continuationMode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "executionIntent": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "targetKind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] } }, "required": [ "mode", "targetKind" ], "additionalProperties": false }, "deliveryIds": { "type": "array", "items": { "type": "string" } }, "deliveryAttempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "jobId": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "dead_lettered" ] }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" }, "responseId": { "type": "string" } }, "required": [ "id", "runId", "jobId", "target", "status" ], "additionalProperties": true } }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "cancelledReason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "jobId", "labels", "createdAt", "updatedAt", "status", "triggeredBy", "target", "execution", "queuedAt", "forceRun", "dueRun", "attempt", "deliveryIds" ], "additionalProperties": true } }, "required": [ "run" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string" } }, "required": [ "runId" ], "additionalProperties": false } } } } } }, "/api/automation/runs/{runId}": { "get": { "operationId": "automation.runs.get", "summary": "Get Automation Run", "description": "Return a single automation run record.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "missed" ] }, "agentId": { "type": "string" }, "triggeredBy": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "scheduleKind": { "type": "string", "enum": [ "at", "every", "cron" ] }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "durationMs": { "type": "number" }, "forceRun": { "type": "boolean" }, "dueRun": { "type": "boolean" }, "attempt": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "route": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "continuationMode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "executionIntent": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "targetKind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] } }, "required": [ "mode", "targetKind" ], "additionalProperties": false }, "deliveryIds": { "type": "array", "items": { "type": "string" } }, "deliveryAttempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "jobId": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "dead_lettered" ] }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" }, "responseId": { "type": "string" } }, "required": [ "id", "runId", "jobId", "target", "status" ], "additionalProperties": true } }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "cancelledReason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "jobId", "labels", "createdAt", "updatedAt", "status", "triggeredBy", "target", "execution", "queuedAt", "forceRun", "dueRun", "attempt", "deliveryIds" ], "additionalProperties": true }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "jobId": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "dead_lettered" ] }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" }, "responseId": { "type": "string" } }, "required": [ "id", "runId", "jobId", "target", "status" ], "additionalProperties": true } } }, "required": [ "run", "deliveries" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:automation" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/automation/runs": { "get": { "operationId": "automation.runs.list", "summary": "List Automation Runs", "description": "Return automation run history. Without ?limit/?cursor returns { runs: [...] } (backward compatible). With ?limit=N (1–500, default 100) and optional ?cursor= returns a PaginatedResponse envelope { items, hasMore, nextCursor? }. Invalid cursors return HTTP 400. Optional ?since= returns only runs active on or after that time (by queuedAt, or endedAt when set), the host-side source an away-digest reads to report the failed, missed, completed, and delivered runs since the operator was last present.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "missed" ] }, "agentId": { "type": "string" }, "triggeredBy": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "scheduleKind": { "type": "string", "enum": [ "at", "every", "cron" ] }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "durationMs": { "type": "number" }, "forceRun": { "type": "boolean" }, "dueRun": { "type": "boolean" }, "attempt": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "route": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "continuationMode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "executionIntent": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "targetKind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] } }, "required": [ "mode", "targetKind" ], "additionalProperties": false }, "deliveryIds": { "type": "array", "items": { "type": "string" } }, "deliveryAttempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "jobId": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "dead_lettered" ] }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" }, "responseId": { "type": "string" } }, "required": [ "id", "runId", "jobId", "target", "status" ], "additionalProperties": true } }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "cancelledReason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "jobId", "labels", "createdAt", "updatedAt", "status", "triggeredBy", "target", "execution", "queuedAt", "forceRun", "dueRun", "attempt", "deliveryIds" ], "additionalProperties": true } } }, "required": [ "runs" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:automation" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/automation/runs/{runId}/retry": { "post": { "operationId": "automation.runs.retry", "summary": "Retry Automation Run", "description": "Retry a completed or failed automation run.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "missed" ] }, "agentId": { "type": "string" }, "triggeredBy": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "scheduleKind": { "type": "string", "enum": [ "at", "every", "cron" ] }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "durationMs": { "type": "number" }, "forceRun": { "type": "boolean" }, "dueRun": { "type": "boolean" }, "attempt": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "route": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "continuationMode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "executionIntent": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "targetKind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] } }, "required": [ "mode", "targetKind" ], "additionalProperties": false }, "deliveryIds": { "type": "array", "items": { "type": "string" } }, "deliveryAttempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "jobId": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "dead_lettered" ] }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" }, "responseId": { "type": "string" } }, "required": [ "id", "runId", "jobId", "target", "status" ], "additionalProperties": true } }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "cancelledReason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "jobId", "labels", "createdAt", "updatedAt", "status", "triggeredBy", "target", "execution", "queuedAt", "forceRun", "dueRun", "attempt", "deliveryIds" ], "additionalProperties": true } }, "required": [ "run" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string" } }, "required": [ "runId" ], "additionalProperties": false } } } } } }, "/api/automation/schedules": { "post": { "operationId": "automation.schedules.create", "summary": "Create Schedule", "description": "Create a schedule record.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "enabled", "paused", "error", "archived" ] }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "fallbackTargets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "includeSummary": { "type": "boolean" }, "includeTranscript": { "type": "boolean" }, "includeLinks": { "type": "boolean" }, "replyToRouteId": { "type": "string" } }, "required": [ "mode", "targets", "fallbackTargets", "includeSummary", "includeTranscript", "includeLinks" ], "additionalProperties": false }, "failure": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "retry", "cooldown", "disable", "dead_letter" ] }, "maxConsecutiveFailures": { "type": "number" }, "cooldownMs": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "delayMs": { "type": "number" }, "strategy": { "type": "string", "enum": [ "fixed", "linear", "exponential" ] }, "maxDelayMs": { "type": "number" }, "jitterMs": { "type": "number" } }, "required": [ "maxAttempts", "delayMs", "strategy" ], "additionalProperties": false }, "deadLetterRouteId": { "type": "string" }, "disableAfterFailures": { "type": "boolean" }, "notifyRouteId": { "type": "string" } }, "required": [ "action", "maxConsecutiveFailures", "cooldownMs", "retryPolicy" ], "additionalProperties": false }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "nextRunAt": { "type": "number" }, "lastRunAt": { "type": "number" }, "lastRunId": { "type": "string" }, "runCount": { "type": "number" }, "successCount": { "type": "number" }, "failureCount": { "type": "number" }, "pausedReason": { "type": "string" }, "deleteAfterRun": { "type": "boolean" }, "archivedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "labels", "createdAt", "updatedAt", "status", "enabled", "schedule", "execution", "delivery", "failure", "source", "runCount", "successCount", "failureCount", "deleteAfterRun" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "prompt": { "type": "string" }, "cron": { "type": "string" }, "every": { "type": "string" }, "at": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" }, "model": { "type": "string" }, "provider": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "reasoningEffort": { "type": "string" }, "thinking": { "type": "string" }, "wakeMode": { "type": "string" }, "timeoutMs": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "type": "string" }, "lightContext": { "type": "boolean" }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "fallbackTargets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "includeSummary": { "type": "boolean" }, "includeTranscript": { "type": "boolean" }, "includeLinks": { "type": "boolean" }, "replyToRouteId": { "type": "string" } }, "required": [ "mode", "targets", "fallbackTargets", "includeSummary", "includeTranscript", "includeLinks" ], "additionalProperties": false }, "failure": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "retry", "cooldown", "disable", "dead_letter" ] }, "maxConsecutiveFailures": { "type": "number" }, "cooldownMs": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "delayMs": { "type": "number" }, "strategy": { "type": "string", "enum": [ "fixed", "linear", "exponential" ] }, "maxDelayMs": { "type": "number" }, "jitterMs": { "type": "number" } }, "required": [ "maxAttempts", "delayMs", "strategy" ], "additionalProperties": false }, "deadLetterRouteId": { "type": "string" }, "disableAfterFailures": { "type": "boolean" }, "notifyRouteId": { "type": "string" } }, "required": [ "action", "maxConsecutiveFailures", "cooldownMs", "retryPolicy" ], "additionalProperties": false }, "enabled": { "type": "boolean" }, "deleteAfterRun": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "cron", "every", "at" ] }, "schedule": { "type": "object", "properties": { "expression": { "type": "string" } }, "required": [ "expression" ], "additionalProperties": false } }, "required": [ "prompt" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "cron": { "type": "string" } }, "required": [ "cron" ], "additionalProperties": true }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "schedule": { "type": "object", "properties": { "expression": { "type": "string" } }, "required": [ "expression" ], "additionalProperties": false } }, "required": [ "schedule" ], "additionalProperties": true }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "every": { "type": "string" } }, "required": [ "every" ], "additionalProperties": true }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "string" } }, "required": [ "at" ], "additionalProperties": true } ] } } } } }, "get": { "operationId": "automation.schedules.list", "summary": "List Schedules", "description": "Return schedule records.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "enabled", "paused", "error", "archived" ] }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "fallbackTargets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } }, "includeSummary": { "type": "boolean" }, "includeTranscript": { "type": "boolean" }, "includeLinks": { "type": "boolean" }, "replyToRouteId": { "type": "string" } }, "required": [ "mode", "targets", "fallbackTargets", "includeSummary", "includeTranscript", "includeLinks" ], "additionalProperties": false }, "failure": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "retry", "cooldown", "disable", "dead_letter" ] }, "maxConsecutiveFailures": { "type": "number" }, "cooldownMs": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "delayMs": { "type": "number" }, "strategy": { "type": "string", "enum": [ "fixed", "linear", "exponential" ] }, "maxDelayMs": { "type": "number" }, "jitterMs": { "type": "number" } }, "required": [ "maxAttempts", "delayMs", "strategy" ], "additionalProperties": false }, "deadLetterRouteId": { "type": "string" }, "disableAfterFailures": { "type": "boolean" }, "notifyRouteId": { "type": "string" } }, "required": [ "action", "maxConsecutiveFailures", "cooldownMs", "retryPolicy" ], "additionalProperties": false }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "nextRunAt": { "type": "number" }, "lastRunAt": { "type": "number" }, "lastRunId": { "type": "string" }, "runCount": { "type": "number" }, "successCount": { "type": "number" }, "failureCount": { "type": "number" }, "pausedReason": { "type": "string" }, "deleteAfterRun": { "type": "boolean" }, "archivedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "labels", "createdAt", "updatedAt", "status", "enabled", "schedule", "execution", "delivery", "failure", "source", "runCount", "successCount", "failureCount", "deleteAfterRun" ], "additionalProperties": true } }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "missed" ] }, "agentId": { "type": "string" }, "triggeredBy": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "manual", "hook", "webhook", "surface", "watcher" ] }, "label": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "routeId": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "execution": { "type": "object", "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "pinnedSessionId": { "type": "string" }, "preserveThread": { "type": "boolean" }, "createIfMissing": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": false }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "routing": { "type": "object", "properties": { "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string" }, "wakeMode": { "type": "string", "enum": [ "next-heartbeat", "now" ] }, "timeoutMs": { "type": "number" }, "maxAttempts": { "type": "number" }, "toolAllowlist": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" }, "sandboxMode": { "type": "string", "enum": [ "inherit", "isolate", "off" ] }, "allowUnsafeExternalContent": { "type": "boolean" }, "externalContentSource": { "anyOf": [ { "type": "string", "enum": [ "gmail", "email", "webhook", "api", "browser", "channel_metadata", "web_search", "web_fetch", "slack", "discord", "ntfy", "unknown" ] }, { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind" ], "additionalProperties": false } ] }, "lightContext": { "type": "boolean" } }, "required": [ "target" ], "additionalProperties": false }, "scheduleKind": { "type": "string", "enum": [ "at", "every", "cron" ] }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "durationMs": { "type": "number" }, "forceRun": { "type": "boolean" }, "dueRun": { "type": "boolean" }, "attempt": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "route": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "continuationMode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "executionIntent": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "spawn", "shared-session", "continued-live", "background" ] }, "targetKind": { "type": "string", "enum": [ "isolated", "current", "pinned", "background", "main", "session", "route" ] } }, "required": [ "mode", "targetKind" ], "additionalProperties": false }, "deliveryIds": { "type": "array", "items": { "type": "string" } }, "deliveryAttempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "jobId": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "dead_lettered" ] }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" }, "responseId": { "type": "string" } }, "required": [ "id", "runId", "jobId", "target", "status" ], "additionalProperties": true } }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "cancelledReason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "jobId", "labels", "createdAt", "updatedAt", "status", "triggeredBy", "target", "execution", "queuedAt", "forceRun", "dueRun", "attempt", "deliveryIds" ], "additionalProperties": true } } }, "required": [ "jobs", "runs" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:automation" ] } }, "/api/automation/schedules/{scheduleId}": { "delete": { "operationId": "automation.schedules.delete", "summary": "Delete Schedule", "description": "Delete a schedule record.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "removed" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "x-dangerous": true, "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/automation/schedules/{scheduleId}/disable": { "post": { "operationId": "automation.schedules.disable", "summary": "Disable Schedule", "description": "Disable a schedule record.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduleId": { "type": "string" } }, "required": [ "scheduleId" ], "additionalProperties": false } } } } } }, "/api/automation/schedules/{scheduleId}/enable": { "post": { "operationId": "automation.schedules.enable", "summary": "Enable Schedule", "description": "Enable a schedule record.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduleId": { "type": "string" } }, "required": [ "scheduleId" ], "additionalProperties": false } } } } } }, "/api/automation/schedules/{scheduleId}/run": { "post": { "operationId": "automation.schedules.run", "summary": "Run Schedule Now", "description": "Trigger a schedule immediately.", "tags": [ "automation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "runId": { "type": "string" }, "agentId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "jobId", "runId", "status" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:automation" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduleId": { "type": "string" } }, "required": [ "scheduleId" ], "additionalProperties": false } } } } } }, "/api/browser/click": { "post": { "operationId": "browser.click", "summary": "Click Element", "description": "Click an element resolved from the latest snapshot of this page. Activating a control that submits a form is an outward effect and is refused when this turn has read untrusted page content.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "clicked": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "urlBefore": { "type": "string" }, "navigated": { "type": "boolean" }, "next": { "type": "string" } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "ref": { "type": "string" }, "button": { "type": "string" }, "clickCount": { "type": "number" }, "timeoutMs": { "type": "number" } }, "required": [ "ref" ], "additionalProperties": true } } } } } }, "/api/browser/extract": { "post": { "operationId": "browser.extract", "summary": "Extract Page Data", "description": "Read named fields out of elements matched by a snapshot ref or a CSS selector. The function that runs in the page is fixed and ships in the engine; there is no way to express code here. Password input values are never returned.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "matched": { "type": "number" }, "returned": { "type": "number" }, "note": { "type": "string" }, "data": { "type": "object", "properties": { "trust": { "type": "string" }, "surface": { "type": "string" }, "origin": { "type": "string" }, "retrievedAt": { "type": "string" }, "text": { "type": "string" }, "truncated": { "type": "boolean" }, "rule": { "type": "string" } }, "required": [ "trust", "surface", "origin", "retrievedAt", "text", "truncated", "rule" ], "additionalProperties": false } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "ref": { "type": "string" }, "selector": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "all": { "type": "boolean" }, "limit": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/browser/history/back": { "post": { "operationId": "browser.history.back", "summary": "Go Back", "description": "Move the page back one entry in its history.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "moved": { "type": "boolean" } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/browser/history/forward": { "post": { "operationId": "browser.history.forward", "summary": "Go Forward", "description": "Move the page forward one entry in its history.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "moved": { "type": "boolean" } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/browser/navigate": { "post": { "operationId": "browser.navigate", "summary": "Navigate", "description": "Load a URL, opening a session first if none is open. http, https, file and about schemes only; a javascript: URL is refused because it runs script against whatever page is already loaded.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "httpStatus": { "type": "number" }, "setup": { "type": "string" }, "next": { "type": "string" } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "waitUntil": { "type": "string" }, "timeoutMs": { "type": "number" }, "profileName": { "type": "string" }, "headless": { "type": "boolean" } }, "required": [ "url" ], "additionalProperties": true } } } } } }, "/api/browser/press": { "post": { "operationId": "browser.press", "summary": "Press Key", "description": "Send one key to an element resolved from the latest snapshot. Enter is treated as a form submission and is an outward effect.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "pressed": { "type": "string" }, "on": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "ref": { "type": "string" }, "key": { "type": "string" }, "timeoutMs": { "type": "number" } }, "required": [ "ref", "key" ], "additionalProperties": true } } } } } }, "/api/browser/provision": { "post": { "operationId": "browser.provision", "summary": "Provision Browser", "description": "Install the browser driver and binary this machine needs, reporting each step it actually ran. Slow on a clean machine; every other verb provisions on demand.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "provision": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } }, "required": [ "provision" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repair": { "type": "boolean" }, "allowDownload": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/browser/read-text": { "post": { "operationId": "browser.readText", "summary": "Read Page Text", "description": "Read the page as text, including open shadow roots and embedded frames, each frame origin recorded separately. Returns the text inside an untrusted-content envelope.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "object", "properties": { "trust": { "type": "string" }, "surface": { "type": "string" }, "origin": { "type": "string" }, "retrievedAt": { "type": "string" }, "text": { "type": "string" }, "truncated": { "type": "boolean" }, "rule": { "type": "string" } }, "required": [ "trust", "surface", "origin", "retrievedAt", "text", "truncated", "rule" ], "additionalProperties": false }, "truncated": { "type": "boolean" } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "maxChars": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/browser/screenshot": { "post": { "operationId": "browser.screenshot", "summary": "Screenshot Page", "description": "Write a PNG of the visible area or the whole scrollable page and report the exact path written.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" }, "bytes": { "type": "number" }, "next": { "type": "string" } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "fullPage": { "type": "boolean" }, "path": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/browser/scroll": { "post": { "operationId": "browser.scroll", "summary": "Scroll Page", "description": "Scroll the page by an amount, or bring a snapshot element into view.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "scrolledBy": { "type": "number" }, "scrolledTo": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "scrollY": { "type": "number" }, "scrollHeight": { "type": "number" } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "ref": { "type": "string" }, "direction": { "type": "string" }, "amount": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/browser/select": { "post": { "operationId": "browser.select", "summary": "Select Options", "description": "Choose option values in a select element resolved from the latest snapshot.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "selectedIn": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "selected": { "type": "array", "items": { "type": "string" } } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "ref": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "timeoutMs": { "type": "number" } }, "required": [ "ref", "values" ], "additionalProperties": true } } } } } }, "/api/browser/sessions/attach": { "post": { "operationId": "browser.sessions.attach", "summary": "Attach To Running Browser", "description": "Connect to a browser already running at a remote debugging endpoint. The daemon can drive it but can never close it.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "sessionId": { "type": "string" }, "origin": { "type": "string" }, "profileDirectory": { "type": "string" }, "cdpEndpoint": { "type": "string" }, "executablePath": { "type": "string" }, "source": { "type": "string" }, "headless": { "type": "boolean" }, "startedAt": { "type": "string" }, "pageCount": { "type": "number" }, "activePageId": { "type": "string" }, "closableByAgent": { "type": "boolean" } }, "required": [ "sessionId", "origin", "headless", "startedAt", "pageCount", "closableByAgent" ], "additionalProperties": false }, "pages": { "type": "array", "items": { "type": "object", "properties": { "pageId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "pageId", "url", "title", "active" ], "additionalProperties": false } }, "note": { "type": "string" } }, "required": [ "session" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cdpEndpoint": { "type": "string" } }, "required": [ "cdpEndpoint" ], "additionalProperties": true } } } } } }, "/api/browser/sessions/close": { "post": { "operationId": "browser.sessions.close", "summary": "Close Browser Session", "description": "End a browser the daemon started. A session attached to a browser the daemon did not start is refused; release it instead.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "closed": { "type": "object", "properties": { "sessionId": { "type": "string" }, "origin": { "type": "string" }, "profileDirectory": { "type": "string" }, "cdpEndpoint": { "type": "string" }, "executablePath": { "type": "string" }, "source": { "type": "string" }, "headless": { "type": "boolean" }, "startedAt": { "type": "string" }, "pageCount": { "type": "number" }, "activePageId": { "type": "string" }, "closableByAgent": { "type": "boolean" } }, "required": [ "sessionId", "origin", "headless", "startedAt", "pageCount", "closableByAgent" ], "additionalProperties": false } }, "required": [ "closed" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" } }, "required": [ "sessionId" ], "additionalProperties": true } } } } } }, "/api/browser/sessions/launch": { "post": { "operationId": "browser.sessions.launch", "summary": "Launch Browser Session", "description": "Start a browser the daemon owns. Pass a profileName to keep sign-ins across runs; headless defaults to true where no display exists.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "sessionId": { "type": "string" }, "origin": { "type": "string" }, "profileDirectory": { "type": "string" }, "cdpEndpoint": { "type": "string" }, "executablePath": { "type": "string" }, "source": { "type": "string" }, "headless": { "type": "boolean" }, "startedAt": { "type": "string" }, "pageCount": { "type": "number" }, "activePageId": { "type": "string" }, "closableByAgent": { "type": "boolean" } }, "required": [ "sessionId", "origin", "headless", "startedAt", "pageCount", "closableByAgent" ], "additionalProperties": false }, "setup": { "type": "string" }, "note": { "type": "string" } }, "required": [ "session" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileName": { "type": "string" }, "headless": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/browser/sessions": { "get": { "operationId": "browser.sessions.list", "summary": "List Browser Sessions", "description": "Return every open browser session, including whether the daemon started it and may therefore close it.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "sessionId": { "type": "string" }, "origin": { "type": "string" }, "profileDirectory": { "type": "string" }, "cdpEndpoint": { "type": "string" }, "executablePath": { "type": "string" }, "source": { "type": "string" }, "headless": { "type": "boolean" }, "startedAt": { "type": "string" }, "pageCount": { "type": "number" }, "activePageId": { "type": "string" }, "closableByAgent": { "type": "boolean" } }, "required": [ "sessionId", "origin", "headless", "startedAt", "pageCount", "closableByAgent" ], "additionalProperties": false } } }, "required": [ "sessions" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:browser" ] } }, "/api/browser/sessions/release": { "post": { "operationId": "browser.sessions.release", "summary": "Release Browser Session", "description": "Disconnect from a session and leave the browser running. This is how an attached browser is let go of.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "released": { "type": "object", "properties": { "sessionId": { "type": "string" }, "origin": { "type": "string" }, "profileDirectory": { "type": "string" }, "cdpEndpoint": { "type": "string" }, "executablePath": { "type": "string" }, "source": { "type": "string" }, "headless": { "type": "boolean" }, "startedAt": { "type": "string" }, "pageCount": { "type": "number" }, "activePageId": { "type": "string" }, "closableByAgent": { "type": "boolean" } }, "required": [ "sessionId", "origin", "headless", "startedAt", "pageCount", "closableByAgent" ], "additionalProperties": false }, "note": { "type": "string" } }, "required": [ "released" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" } }, "required": [ "sessionId" ], "additionalProperties": true } } } } } }, "/api/browser/snapshot": { "post": { "operationId": "browser.snapshot", "summary": "Snapshot Page", "description": "Return addressable element refs for the current page. Element names come from the page, so the result is untrusted content and is labelled as such.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "contentTrust": { "type": "string" }, "origin": { "type": "string" }, "rule": { "type": "string" }, "snapshotId": { "type": "string" }, "elementCount": { "type": "number" }, "truncated": { "type": "boolean" }, "elements": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "role": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "disabled": { "type": "boolean" }, "checked": { "type": "boolean" } }, "required": [ "ref", "role", "name" ], "additionalProperties": false } } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "limit": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/browser/status": { "get": { "operationId": "browser.status", "summary": "Browser Status", "description": "Report whether a browser is available on this machine, where its binary came from, whether a display exists, and which sessions are open.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "browserAvailable": { "type": "boolean" }, "binarySource": { "type": "string" }, "executablePath": { "type": "string" }, "driverVersion": { "type": "string" }, "browsersPath": { "type": "string" }, "displayAvailable": { "type": "boolean" }, "defaultMode": { "type": "string" }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "sessionId": { "type": "string" }, "origin": { "type": "string" }, "profileDirectory": { "type": "string" }, "cdpEndpoint": { "type": "string" }, "executablePath": { "type": "string" }, "source": { "type": "string" }, "headless": { "type": "boolean" }, "startedAt": { "type": "string" }, "pageCount": { "type": "number" }, "activePageId": { "type": "string" }, "closableByAgent": { "type": "boolean" } }, "required": [ "sessionId", "origin", "headless", "startedAt", "pageCount", "closableByAgent" ], "additionalProperties": false } }, "provisionSteps": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } }, "problem": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "browserAvailable" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:browser" ] } }, "/api/browser/tabs/close": { "post": { "operationId": "browser.tabs.close", "summary": "Close Tab", "description": "Close one tab. The browser itself keeps running.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "closedPageId": { "type": "string" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "pageId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "pageId", "url", "title", "active" ], "additionalProperties": false } } }, "required": [ "sessionId", "closedPageId", "pages" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" } }, "required": [ "pageId" ], "additionalProperties": true } } } } } }, "/api/browser/tabs": { "post": { "operationId": "browser.tabs.create", "summary": "Open Tab", "description": "Open a new tab, optionally at a URL, opening a session first if none is open.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "pageId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "pageId", "url", "title", "active" ], "additionalProperties": false } } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "profileName": { "type": "string" }, "headless": { "type": "boolean" } }, "additionalProperties": true } } } } }, "get": { "operationId": "browser.tabs.list", "summary": "List Tabs", "description": "Return every open page in a session, with which one is active.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "pageId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "pageId", "url", "title", "active" ], "additionalProperties": false } } }, "required": [ "sessionId", "pages" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:browser" ], "parameters": [ { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/browser/tabs/switch": { "post": { "operationId": "browser.tabs.switch", "summary": "Switch Tab", "description": "Make another open tab the active one for later page verbs.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "activePageId": { "type": "string" } }, "required": [ "sessionId", "activePageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" } }, "required": [ "pageId" ], "additionalProperties": true } } } } } }, "/api/browser/type": { "post": { "operationId": "browser.type", "summary": "Type Into Element", "description": "Type into an element resolved from the latest snapshot. There is no variant that types into whatever window has focus. submit:true presses Enter afterwards and is an outward effect.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "typedInto": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "submitted": { "type": "boolean" } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:browser" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "ref": { "type": "string" }, "text": { "type": "string" }, "submit": { "type": "boolean" }, "replace": { "type": "boolean" }, "timeoutMs": { "type": "number" } }, "required": [ "ref", "text" ], "additionalProperties": true } } } } } }, "/api/browser/wait-for": { "post": { "operationId": "browser.waitFor", "summary": "Wait For Page State", "description": "Wait for text to become visible, for the URL to match, or for the network to settle. The timeout bounds this call only and never ends the browser.", "tags": [ "browser" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "url": { "type": "string" }, "waitedFor": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "found": { "type": "boolean" } }, "required": [ "sessionId", "pageId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:browser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "text": { "type": "string" }, "url": { "type": "string" }, "timeoutMs": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/calendar/events": { "post": { "operationId": "calendar.events.create", "summary": "Create Calendar Event", "description": "Create an event on the configured CalDAV calendar. Requires explicit confirmation.", "tags": [ "calendar" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "uid": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "eventId", "uid", "createdAt" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:calendar" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "description": { "type": "string" }, "attendees": { "type": "array", "items": { "type": "string" } }, "location": { "type": "string" }, "calendarId": { "type": "string" }, "confirm": { "type": "boolean" } }, "required": [ "title", "start", "end", "confirm" ], "additionalProperties": true } } } } }, "get": { "operationId": "calendar.events.list", "summary": "List Calendar Events", "description": "Return calendar event summaries from the configured CalDAV calendar within an optional time window.", "tags": [ "calendar" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "string" }, "description": { "type": "string" }, "attendees": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "title", "start", "end" ], "additionalProperties": false } } }, "required": [ "events" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:calendar" ], "parameters": [ { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/calendar/events/{eventId}": { "get": { "operationId": "calendar.events.get", "summary": "Get Calendar Event", "description": "Return the full event object including attendees, recurrence, and raw iCalendar UID.", "tags": [ "calendar" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "uid": { "type": "string" }, "title": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "string" }, "description": { "type": "string" }, "attendees": { "type": "array", "items": { "type": "string" } }, "recurrence": { "type": "string" } }, "required": [ "id", "title", "start", "end" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:calendar" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/calendar/ics/export": { "get": { "operationId": "calendar.ics.export", "summary": "Export iCalendar", "description": "Export events from the configured CalDAV calendar as raw .ics content within an optional time window.", "tags": [ "calendar" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "icsContent": { "type": "string" }, "eventCount": { "type": "number" } }, "required": [ "icsContent", "eventCount" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:calendar" ], "parameters": [ { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/calendar/ics/import": { "post": { "operationId": "calendar.ics.import", "summary": "Import iCalendar", "description": "Import raw .ics content into the configured CalDAV calendar. Requires explicit confirmation.", "tags": [ "calendar" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "number" }, "eventIds": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "imported", "eventIds", "errors" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:calendar" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "icsContent": { "type": "string" }, "calendarId": { "type": "string" }, "confirm": { "type": "boolean" } }, "required": [ "icsContent", "confirm" ], "additionalProperties": true } } } } } }, "/api/channels/accounts/{surface}/actions/{action}": { "post": { "operationId": "channels.accounts.action.default", "summary": "Run Channel Account Action", "description": "Run a lifecycle action on the default channel account for a surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "accountId": { "type": "string" }, "action": { "type": "string" }, "result": { "type": "object", "properties": { "surface": { "type": "string" }, "accountId": { "type": "string" }, "action": { "type": "string" }, "ok": { "type": "boolean" }, "state": { "type": "string" }, "authState": { "type": "string" }, "account": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" }, "linked": { "type": "boolean" }, "state": { "type": "string" }, "authState": { "type": "string" }, "accountId": { "type": "string" }, "workspaceId": { "type": "string" }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "source": { "type": "string" } }, "required": [ "field", "label", "configured", "source" ], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "id", "label", "kind", "available" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "enabled", "configured", "linked", "state", "authState", "secrets", "actions", "metadata" ], "additionalProperties": false }, { "type": "null" } ] }, "message": { "type": "string" }, "login": { "type": "object", "properties": { "kind": { "type": "string" }, "url": { "type": "string" }, "qr": { "type": "string" }, "expiresAt": { "type": "number" }, "instructions": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "action", "ok", "metadata" ], "additionalProperties": false } }, "required": [ "surface", "action", "result" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/channels/accounts/{surface}/{accountId}/actions/{action}": { "post": { "operationId": "channels.accounts.action.named", "summary": "Run Named Channel Account Action", "description": "Run a lifecycle action on a specific channel account.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "accountId": { "type": "string" }, "action": { "type": "string" }, "result": { "type": "object", "properties": { "surface": { "type": "string" }, "accountId": { "type": "string" }, "action": { "type": "string" }, "ok": { "type": "boolean" }, "state": { "type": "string" }, "authState": { "type": "string" }, "account": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" }, "linked": { "type": "boolean" }, "state": { "type": "string" }, "authState": { "type": "string" }, "accountId": { "type": "string" }, "workspaceId": { "type": "string" }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "source": { "type": "string" } }, "required": [ "field", "label", "configured", "source" ], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "id", "label", "kind", "available" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "enabled", "configured", "linked", "state", "authState", "secrets", "actions", "metadata" ], "additionalProperties": false }, { "type": "null" } ] }, "message": { "type": "string" }, "login": { "type": "object", "properties": { "kind": { "type": "string" }, "url": { "type": "string" }, "qr": { "type": "string" }, "expiresAt": { "type": "number" }, "instructions": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "action", "ok", "metadata" ], "additionalProperties": false } }, "required": [ "surface", "action", "result" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/channels/accounts/{surface}/{accountId}": { "get": { "operationId": "channels.accounts.get", "summary": "Get Channel Account", "description": "Return a single channel account record.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" }, "linked": { "type": "boolean" }, "state": { "type": "string" }, "authState": { "type": "string" }, "accountId": { "type": "string" }, "workspaceId": { "type": "string" }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "source": { "type": "string" } }, "required": [ "field", "label", "configured", "source" ], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "id", "label", "kind", "available" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "enabled", "configured", "linked", "state", "authState", "secrets", "actions", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/accounts": { "get": { "operationId": "channels.accounts.list", "summary": "List Channel Accounts", "description": "Return channel account lifecycle posture.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" }, "linked": { "type": "boolean" }, "state": { "type": "string" }, "authState": { "type": "string" }, "accountId": { "type": "string" }, "workspaceId": { "type": "string" }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "source": { "type": "string" } }, "required": [ "field", "label", "configured", "source" ], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "id", "label", "kind", "available" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "enabled", "configured", "linked", "state", "authState", "secrets", "actions", "metadata" ], "additionalProperties": false } } }, "required": [ "accounts" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ] } }, "/api/channels/accounts/{surface}": { "get": { "operationId": "channels.accounts.surface.list", "summary": "List Channel Surface Accounts", "description": "Return account posture for a single channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" }, "linked": { "type": "boolean" }, "state": { "type": "string" }, "authState": { "type": "string" }, "accountId": { "type": "string" }, "workspaceId": { "type": "string" }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "source": { "type": "string" } }, "required": [ "field", "label", "configured", "source" ], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "id", "label", "kind", "available" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "enabled", "configured", "linked", "state", "authState", "secrets", "actions", "metadata" ], "additionalProperties": false } } }, "required": [ "accounts" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/actions/{surface}/{actionId}": { "post": { "operationId": "channels.actions.invoke", "summary": "Run Channel Action", "description": "Run a channel-owned operator action.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string" }, "surface": { "type": "string" }, "result": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "actionId", "surface", "result" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/channels/actions": { "get": { "operationId": "channels.actions.list", "summary": "List Channel Actions", "description": "Return operator actions registered by channel plugins.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "dangerous": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "description", "dangerous", "metadata" ], "additionalProperties": false } } }, "required": [ "actions" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ] } }, "/api/channels/actions/{surface}": { "get": { "operationId": "channels.actions.surface.list", "summary": "List Channel Surface Actions", "description": "Return operator actions for a single channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "dangerous": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "description", "dangerous", "metadata" ], "additionalProperties": false } } }, "required": [ "actions" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/agent-tools": { "get": { "operationId": "channels.agent_tools.list", "summary": "List Channel Agent Tools", "description": "Return LLM agent tools exposed through channel plugins.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "sideEffects": { "type": "array", "items": { "type": "string" } }, "concurrency": { "type": "string" }, "supportsProgress": { "type": "boolean" }, "supportsStreamingOutput": { "type": "boolean" } }, "required": [ "name", "description", "parameters" ], "additionalProperties": false } } }, "required": [ "tools" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ] } }, "/api/channels/agent-tools/{surface}": { "get": { "operationId": "channels.agent_tools.surface.list", "summary": "List Channel Surface Agent Tools", "description": "Return LLM agent tools for a single channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "sideEffects": { "type": "array", "items": { "type": "string" } }, "concurrency": { "type": "string" }, "supportsProgress": { "type": "boolean" }, "supportsStreamingOutput": { "type": "boolean" } }, "required": [ "name", "description", "parameters" ], "additionalProperties": false } } }, "required": [ "tools" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/allowlist/{surface}/edit": { "post": { "operationId": "channels.allowlist.edit", "summary": "Edit Channel Allowlist", "description": "Apply allowlist additions or removals for a channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "updatedPolicy": { "type": "object", "properties": { "surface": { "type": "string" }, "enabled": { "type": "boolean" }, "requireMention": { "type": "boolean" }, "allowDirectMessages": { "type": "boolean" }, "allowGroupMessages": { "type": "boolean" }, "allowThreadMessages": { "type": "boolean" }, "dmPolicy": { "type": "string" }, "groupPolicy": { "type": "string" }, "allowTextCommandsWithoutMention": { "type": "boolean" }, "allowlistUserIds": { "type": "array", "items": { "type": "string" } }, "allowlistChannelIds": { "type": "array", "items": { "type": "string" } }, "allowlistGroupIds": { "type": "array", "items": { "type": "string" } }, "allowedCommands": { "type": "array", "items": { "type": "string" } }, "groupPolicies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "groupId": { "type": "string" }, "channelId": { "type": "string" }, "workspaceId": { "type": "string" }, "requireMention": { "type": "boolean" }, "allowGroupMessages": { "type": "boolean" }, "allowThreadMessages": { "type": "boolean" }, "allowTextCommandsWithoutMention": { "type": "boolean" }, "allowlistUserIds": { "type": "array", "items": { "type": "string" } }, "allowlistChannelIds": { "type": "array", "items": { "type": "string" } }, "allowlistGroupIds": { "type": "array", "items": { "type": "string" } }, "allowedCommands": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id" ], "additionalProperties": false } }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "enabled", "requireMention", "allowDirectMessages", "allowGroupMessages", "allowThreadMessages", "dmPolicy", "groupPolicy", "allowTextCommandsWithoutMention", "allowlistUserIds", "allowlistChannelIds", "allowlistGroupIds", "allowedCommands", "groupPolicies", "updatedAt", "metadata" ], "additionalProperties": false }, "resolution": { "type": "object", "properties": { "surface": { "type": "string" }, "resolved": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "input": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind", "input", "id", "label", "metadata" ], "additionalProperties": false } }, "unresolved": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "resolved", "unresolved", "metadata" ], "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "updatedPolicy", "resolution", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "add": { "type": "array", "items": { "type": "string" } }, "remove": { "type": "array", "items": { "type": "string" } }, "groupId": { "type": "string" }, "channelId": { "type": "string" }, "workspaceId": { "type": "string" }, "kind": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/channels/allowlist/{surface}/resolve": { "post": { "operationId": "channels.allowlist.resolve", "summary": "Resolve Channel Allowlist", "description": "Resolve allowlist candidates into stable channel identities.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "resolved": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "input": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind", "input", "id", "label", "metadata" ], "additionalProperties": false } }, "unresolved": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "resolved", "unresolved", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "add": { "type": "array", "items": { "type": "string" } }, "remove": { "type": "array", "items": { "type": "string" } }, "groupId": { "type": "string" }, "channelId": { "type": "string" }, "workspaceId": { "type": "string" }, "kind": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/channels/authorize/{surface}": { "post": { "operationId": "channels.authorize", "summary": "Authorize Channel Action", "description": "Evaluate channel authorization and availability for a requested action.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "result": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string" }, "account": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" }, "linked": { "type": "boolean" }, "state": { "type": "string" }, "authState": { "type": "string" }, "accountId": { "type": "string" }, "workspaceId": { "type": "string" }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "source": { "type": "string" } }, "required": [ "field", "label", "configured", "source" ], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "id", "label", "kind", "available" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "enabled", "configured", "linked", "state", "authState", "secrets", "actions", "metadata" ], "additionalProperties": false }, { "type": "null" } ] }, "actionAvailable": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "allowed", "reason", "metadata" ], "additionalProperties": false } }, "required": [ "surface", "result" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string" }, "actorId": { "type": "string" }, "accountId": { "type": "string" }, "target": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "actionId" ], "additionalProperties": true } } } } } }, "/api/channels/capabilities": { "get": { "operationId": "channels.capabilities.list", "summary": "List Channel Capabilities", "description": "Return capability posture for all registered channel surfaces.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "scope": { "type": "string" }, "supported": { "type": "boolean" }, "detail": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "scope", "supported", "detail", "metadata" ], "additionalProperties": false } } }, "required": [ "capabilities" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ] } }, "/api/channels/capabilities/{surface}": { "get": { "operationId": "channels.capabilities.surface.list", "summary": "List Channel Surface Capabilities", "description": "Return capability posture for a single surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "scope": { "type": "string" }, "supported": { "type": "boolean" }, "detail": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "scope", "supported", "detail", "metadata" ], "additionalProperties": false } } }, "required": [ "capabilities" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/directory/{surface}": { "get": { "operationId": "channels.directory.query", "summary": "Query Channel Directory", "description": "Query a channel directory surface for users, groups, threads, or services.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "handle": { "type": "string" }, "accountId": { "type": "string" }, "workspaceId": { "type": "string" }, "groupId": { "type": "string" }, "threadId": { "type": "string" }, "parentId": { "type": "string" }, "memberCount": { "type": "number" }, "memberIds": { "type": "array", "items": { "type": "string" } }, "aliases": { "type": "array", "items": { "type": "string" } }, "isSelf": { "type": "boolean" }, "isDirect": { "type": "boolean" }, "isGroupConversation": { "type": "boolean" }, "searchText": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "kind", "label", "metadata" ], "additionalProperties": false } } }, "required": [ "entries" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "groupId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "live", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/channels/doctor/{surface}": { "get": { "operationId": "channels.doctor.get", "summary": "Get Channel Doctor Report", "description": "Return doctor checks and repair posture for a channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "accountId": { "type": "string" }, "state": { "type": "string" }, "summary": { "type": "string" }, "checkedAt": { "type": "number" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "detail": { "type": "string" }, "repairActionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "status", "detail" ], "additionalProperties": false } }, "repairActions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "dangerous": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "description", "dangerous", "metadata" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "state", "summary", "checkedAt", "checks", "repairActions", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/drafts/{draftId}": { "delete": { "operationId": "channels.drafts.delete", "summary": "Delete Channel Draft", "description": "Remove a channel draft from the daemon-side store.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "draftId": { "type": "string" } }, "required": [ "deleted", "draftId" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "x-dangerous": true, "parameters": [ { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "get": { "operationId": "channels.drafts.get", "summary": "Get Channel Draft", "description": "Return a single daemon-mirrored channel draft by id, or a notFound marker.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" }, "channel": { "type": "string" }, "route": { "type": "string" }, "webhook": { "type": "string" }, "link": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "sentResponseId": { "type": "string" }, "sendError": { "type": "string" }, "notFound": { "type": "boolean" } }, "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/drafts": { "get": { "operationId": "channels.drafts.list", "summary": "List Channel Drafts", "description": "Return daemon-mirrored channel drafts for cross-device sync. Webhook values are stored redacted.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "drafts": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "number" }, "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" }, "channel": { "type": "string" }, "route": { "type": "string" }, "webhook": { "type": "string" }, "link": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "sentResponseId": { "type": "string" }, "sendError": { "type": "string" } }, "required": [ "version", "id", "createdAt", "updatedAt", "status", "message" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "drafts", "total" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] }, "post": { "operationId": "channels.drafts.save", "summary": "Save Channel Draft", "description": "Mirror a channel draft to the daemon-side store. Webhook values must be redacted before transmission; raw webhook tokens are rejected. Requires explicit confirmation.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "version": { "type": "number" }, "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" }, "channel": { "type": "string" }, "route": { "type": "string" }, "webhook": { "type": "string" }, "link": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "sentResponseId": { "type": "string" }, "sendError": { "type": "string" } }, "required": [ "version", "id", "createdAt", "updatedAt", "status", "message" ], "additionalProperties": false }, "created": { "type": "boolean" } }, "required": [ "draft", "created" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" }, "channel": { "type": "string" }, "route": { "type": "string" }, "webhook": { "type": "string" }, "link": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "sentResponseId": { "type": "string" }, "sendError": { "type": "string" } }, "required": [ "version", "id", "createdAt", "updatedAt", "status", "message" ], "additionalProperties": true } } } } } }, "/api/channels/inbox": { "get": { "operationId": "channels.inbox.list", "summary": "List Channel Inbox", "description": "Return the merged inbound message feed (Slack DMs, Discord messages, email threads) from the host's synced provider mirror, newest first. Read-only; no provider write. Every known provider reports its own state in `providers`, including the unconfigured and the failing ones, so a short list is never ambiguous, and `partial` is true whenever a configured provider's items are missing because its last sync failed. Page with ?limit and ?cursor (opaque, from nextCursor); ?since= returns only items newer than a previous answer's `cursor` watermark; ?provider= narrows to one provider.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "kind": { "type": "string" }, "from": { "type": "string" }, "fromAddress": { "type": "string" }, "subject": { "type": "string" }, "bodyPreview": { "type": "string" }, "receivedAt": { "type": "number" }, "unread": { "type": "boolean" }, "routeId": { "type": "string" }, "threadId": { "type": "string" }, "attachmentCount": { "type": "number" }, "triageScore": { "type": "number" }, "triageLabel": { "type": "string" }, "triageTags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "provider", "kind", "from", "bodyPreview", "receivedAt", "unread" ], "additionalProperties": false } }, "total": { "type": "number" }, "truncated": { "type": "boolean" }, "hasMore": { "type": "boolean" }, "cursor": { "type": "string" }, "nextCursor": { "type": "string" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "state": { "type": "string" }, "itemCount": { "type": "number" }, "storedCount": { "type": "number" }, "configured": { "type": "boolean" }, "lastSyncAt": { "type": "number" }, "syncing": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "provider", "state", "itemCount", "storedCount" ], "additionalProperties": false } }, "partial": { "type": "boolean" } }, "required": [ "items", "total", "truncated", "hasMore", "providers", "partial" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/channels/lifecycle/{surface}": { "get": { "operationId": "channels.lifecycle.get", "summary": "Get Channel Lifecycle State", "description": "Return lifecycle version posture for a channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "accountId": { "type": "string" }, "currentVersion": { "type": "number" }, "targetVersion": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "currentVersion", "targetVersion", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/policies/audit": { "get": { "operationId": "channels.policies.audit", "summary": "List Channel Policy Audit", "description": "Return channel ingress policy audit records.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "createdAt": { "type": "number" }, "allowed": { "type": "boolean" }, "reason": { "type": "string" }, "userId": { "type": "string" }, "channelId": { "type": "string" }, "groupId": { "type": "string" }, "threadId": { "type": "string" }, "conversationKind": { "type": "string" }, "matchedGroupPolicyId": { "type": "string" }, "text": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "createdAt", "allowed", "reason", "metadata" ], "additionalProperties": false } } }, "required": [ "audit" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/channels/policies": { "get": { "operationId": "channels.policies.list", "summary": "List Channel Policies", "description": "Return ingress policy configuration for channels.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "type": "array", "items": { "type": "object", "properties": { "surface": { "type": "string" }, "enabled": { "type": "boolean" }, "requireMention": { "type": "boolean" }, "allowDirectMessages": { "type": "boolean" }, "allowGroupMessages": { "type": "boolean" }, "allowThreadMessages": { "type": "boolean" }, "dmPolicy": { "type": "string" }, "groupPolicy": { "type": "string" }, "allowTextCommandsWithoutMention": { "type": "boolean" }, "allowlistUserIds": { "type": "array", "items": { "type": "string" } }, "allowlistChannelIds": { "type": "array", "items": { "type": "string" } }, "allowlistGroupIds": { "type": "array", "items": { "type": "string" } }, "allowedCommands": { "type": "array", "items": { "type": "string" } }, "groupPolicies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "groupId": { "type": "string" }, "channelId": { "type": "string" }, "workspaceId": { "type": "string" }, "requireMention": { "type": "boolean" }, "allowGroupMessages": { "type": "boolean" }, "allowThreadMessages": { "type": "boolean" }, "allowTextCommandsWithoutMention": { "type": "boolean" }, "allowlistUserIds": { "type": "array", "items": { "type": "string" } }, "allowlistChannelIds": { "type": "array", "items": { "type": "string" } }, "allowlistGroupIds": { "type": "array", "items": { "type": "string" } }, "allowedCommands": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id" ], "additionalProperties": false } }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "enabled", "requireMention", "allowDirectMessages", "allowGroupMessages", "allowThreadMessages", "dmPolicy", "groupPolicy", "allowTextCommandsWithoutMention", "allowlistUserIds", "allowlistChannelIds", "allowlistGroupIds", "allowedCommands", "groupPolicies", "updatedAt", "metadata" ], "additionalProperties": false } } }, "required": [ "policies" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ] } }, "/api/channels/policies/{surface}": { "post": { "operationId": "channels.policies.update", "summary": "Update Channel Policy", "description": "Update ingress policy configuration for a channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "enabled": { "type": "boolean" }, "requireMention": { "type": "boolean" }, "allowDirectMessages": { "type": "boolean" }, "allowGroupMessages": { "type": "boolean" }, "allowThreadMessages": { "type": "boolean" }, "dmPolicy": { "type": "string" }, "groupPolicy": { "type": "string" }, "allowTextCommandsWithoutMention": { "type": "boolean" }, "allowlistUserIds": { "type": "array", "items": { "type": "string" } }, "allowlistChannelIds": { "type": "array", "items": { "type": "string" } }, "allowlistGroupIds": { "type": "array", "items": { "type": "string" } }, "allowedCommands": { "type": "array", "items": { "type": "string" } }, "groupPolicies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "groupId": { "type": "string" }, "channelId": { "type": "string" }, "workspaceId": { "type": "string" }, "requireMention": { "type": "boolean" }, "allowGroupMessages": { "type": "boolean" }, "allowThreadMessages": { "type": "boolean" }, "allowTextCommandsWithoutMention": { "type": "boolean" }, "allowlistUserIds": { "type": "array", "items": { "type": "string" } }, "allowlistChannelIds": { "type": "array", "items": { "type": "string" } }, "allowlistGroupIds": { "type": "array", "items": { "type": "string" } }, "allowedCommands": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id" ], "additionalProperties": false } }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "enabled", "requireMention", "allowDirectMessages", "allowGroupMessages", "allowThreadMessages", "dmPolicy", "groupPolicy", "allowTextCommandsWithoutMention", "allowlistUserIds", "allowlistChannelIds", "allowlistGroupIds", "allowedCommands", "groupPolicies", "updatedAt", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "requireMention": { "type": "boolean" }, "allowDirectMessages": { "type": "boolean" }, "allowGroupMessages": { "type": "boolean" }, "allowThreadMessages": { "type": "boolean" }, "dmPolicy": { "type": "string" }, "groupPolicy": { "type": "string" }, "allowTextCommandsWithoutMention": { "type": "boolean" }, "allowlistUserIds": { "type": "array", "items": { "type": "string" } }, "allowlistChannelIds": { "type": "array", "items": { "type": "string" } }, "allowlistGroupIds": { "type": "array", "items": { "type": "string" } }, "allowedCommands": { "type": "array", "items": { "type": "string" } }, "groupPolicies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "groupId": { "type": "string" }, "channelId": { "type": "string" }, "workspaceId": { "type": "string" }, "requireMention": { "type": "boolean" }, "allowGroupMessages": { "type": "boolean" }, "allowThreadMessages": { "type": "boolean" }, "allowTextCommandsWithoutMention": { "type": "boolean" }, "allowlistUserIds": { "type": "array", "items": { "type": "string" } }, "allowlistChannelIds": { "type": "array", "items": { "type": "string" } }, "allowlistGroupIds": { "type": "array", "items": { "type": "string" } }, "allowedCommands": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/channels/profiles/{surfaceKind}": { "delete": { "operationId": "channels.profiles.delete", "summary": "Unbind Channel Profile", "description": "Remove a channel profile binding. Returns { deleted: false } when no binding for that key existed, an honest boolean, never a phantom removal.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "channelId": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "surfaceKind", "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "x-dangerous": true, "parameters": [ { "name": "surfaceKind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channelId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "get": { "operationId": "channels.profiles.get", "summary": "Get Channel Profile Binding", "description": "Return the profile binding for a channel (surfaceKind plus optional channelId). Returns 404 when no binding for that exact key exists.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "binding": { "type": "object", "properties": { "id": { "type": "string" }, "surfaceKind": { "type": "string" }, "channelId": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "permissionMode": { "type": "string", "enum": [ "plan", "normal", "accept-edits", "auto" ] }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surfaceKind", "updatedAt" ], "additionalProperties": false } }, "required": [ "binding" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surfaceKind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channelId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/channels/profiles": { "get": { "operationId": "channels.profiles.list", "summary": "List Channel Profile Bindings", "description": "Return every per-channel profile binding (the model/permission defaults applied to sessions each channel originates).", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bindings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surfaceKind": { "type": "string" }, "channelId": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "permissionMode": { "type": "string", "enum": [ "plan", "normal", "accept-edits", "auto" ] }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surfaceKind", "updatedAt" ], "additionalProperties": false } } }, "required": [ "bindings" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ] }, "post": { "operationId": "channels.profiles.set", "summary": "Bind Channel Profile", "description": "Bind (upsert) the model/provider and permission-mode defaults for a channel. Keyed on (surfaceKind, channelId?): a channelId-scoped binding wins over the surface-wide default; setting the same key again replaces it.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "binding": { "type": "object", "properties": { "id": { "type": "string" }, "surfaceKind": { "type": "string" }, "channelId": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "permissionMode": { "type": "string", "enum": [ "plan", "normal", "accept-edits", "auto" ] }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surfaceKind", "updatedAt" ], "additionalProperties": false } }, "required": [ "binding" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "channelId": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "permissionMode": { "type": "string", "enum": [ "plan", "normal", "accept-edits", "auto" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surfaceKind" ], "additionalProperties": false } } } } } }, "/api/channels/repair-actions/{surface}": { "get": { "operationId": "channels.repairs.list", "summary": "List Channel Repair Actions", "description": "Return repair actions exposed by a channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "dangerous": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "description", "dangerous", "metadata" ], "additionalProperties": false } } }, "required": [ "actions" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/routing": { "post": { "operationId": "channels.routing.assign", "summary": "Assign Channel Routing Rule", "description": "Create or update a channel-to-profile routing rule in the daemon-persisted routing table. Requires explicit confirmation.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "assignmentId": { "type": "string" }, "channelId": { "type": "string" }, "surfaceKind": { "type": "string" }, "routeId": { "type": "string" }, "profileId": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "assignmentId", "surfaceKind", "profileId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channelId": { "type": "string" }, "surfaceKind": { "type": "string" }, "routeId": { "type": "string" }, "profileId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "surfaceKind", "profileId" ], "additionalProperties": true } } } } }, "get": { "operationId": "channels.routing.list", "summary": "List Channel Routing Rules", "description": "Return the daemon-persisted channel-to-profile routing table.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "surfaceKind": { "type": "string" }, "routeId": { "type": "string" }, "profileId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "createdAt", "updatedAt", "surfaceKind", "profileId" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "routes", "total" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "profileId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "surfaceKind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/channels/routing/{assignmentId}": { "delete": { "operationId": "channels.routing.delete", "summary": "Delete Channel Routing Rule", "description": "Remove a channel-to-profile routing rule from the daemon-persisted routing table.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "assignmentId": { "type": "string" } }, "required": [ "deleted", "assignmentId" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "x-dangerous": true, "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/setup/{surface}": { "get": { "operationId": "channels.setup.get", "summary": "Get Channel Setup Schema", "description": "Return the versioned setup schema, secret targets, and external steps for a channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "version": { "type": "number" }, "label": { "type": "string" }, "setupMode": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "required": { "type": "boolean" }, "detail": { "type": "string" }, "placeholder": { "type": "string" }, "configKey": { "type": "string" }, "secretTargetId": { "type": "string" }, "defaultValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "kind", "required", "metadata" ], "additionalProperties": false } }, "secretTargets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "supports": { "type": "array", "items": { "type": "string" } }, "serviceName": { "type": "string" }, "serviceField": { "type": "string" }, "envKeys": { "type": "array", "items": { "type": "string" } }, "configKeys": { "type": "array", "items": { "type": "string" } }, "detail": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "required", "supports", "metadata" ], "additionalProperties": false } }, "externalSteps": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "version", "label", "setupMode", "description", "fields", "secretTargets", "externalSteps", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/channels/status": { "get": { "operationId": "channels.status", "summary": "Channel Status", "description": "Return status for channel plugins and provider-backed channels.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string" }, "enabled": { "type": "boolean" }, "accountId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "label", "state", "enabled", "metadata" ], "additionalProperties": false } } }, "required": [ "channels" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ] } }, "/api/channels/targets/{surface}/resolve": { "post": { "operationId": "channels.targets.resolve", "summary": "Resolve Channel Target", "description": "Resolve a typed channel target for outbound delivery or routing.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "string" }, "target": { "type": "object", "properties": { "surface": { "type": "string" }, "input": { "type": "string" }, "normalized": { "type": "string" }, "kind": { "type": "string" }, "to": { "type": "string" }, "display": { "type": "string" }, "accountId": { "type": "string" }, "workspaceId": { "type": "string" }, "channelId": { "type": "string" }, "groupId": { "type": "string" }, "threadId": { "type": "string" }, "parentId": { "type": "string" }, "sessionId": { "type": "string" }, "sessionTarget": { "type": "string" }, "bindingId": { "type": "string" }, "directoryEntryId": { "type": "string" }, "source": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "surface", "input", "normalized", "kind", "to", "source", "metadata" ], "additionalProperties": false } }, "required": [ "surface", "target" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string" }, "input": { "type": "string" }, "query": { "type": "string" }, "accountId": { "type": "string" }, "preferredKind": { "type": "string" }, "threadId": { "type": "string" }, "sessionId": { "type": "string" }, "createIfMissing": { "type": "boolean" }, "live": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "target": { "type": "string" } }, "required": [ "target" ], "additionalProperties": true }, { "type": "object", "properties": { "input": { "type": "string" } }, "required": [ "input" ], "additionalProperties": true }, { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ], "additionalProperties": true } ] } } } } } }, "/api/channels/tools/{surface}/{toolId}": { "post": { "operationId": "channels.tools.invoke", "summary": "Run Channel Tool", "description": "Run a channel-owned operator tool.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "toolId": { "type": "string" }, "surface": { "type": "string" }, "result": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "toolId", "surface", "result" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "toolId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/channels/tools": { "get": { "operationId": "channels.tools.list", "summary": "List Channel Tools", "description": "Return operator tools registered by channel plugins.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "actionIds": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "name", "description", "actionIds", "metadata" ], "additionalProperties": false } } }, "required": [ "tools" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ] } }, "/api/channels/tools/{surface}": { "get": { "operationId": "channels.tools.surface.list", "summary": "List Channel Surface Tools", "description": "Return operator tools for a single channel surface.", "tags": [ "channels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "actionIds": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "name", "description", "actionIds", "metadata" ], "additionalProperties": false } } }, "required": [ "tools" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:channels" ], "parameters": [ { "name": "surface", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/checkin/config": { "get": { "operationId": "checkin.config.get", "summary": "Get Check-in Config", "description": "Return the proactive check-in configuration: enabled, cadence (cron), delivery channel, and quiet hours.", "tags": [ "checkin" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string" }, "deliveryChannel": { "type": "string" }, "quietHours": { "type": "string" } }, "required": [ "enabled", "cadence", "deliveryChannel", "quietHours" ], "additionalProperties": false } }, "required": [ "config" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:checkin" ] }, "post": { "operationId": "checkin.config.set", "summary": "Update Check-in Config", "description": "Update the proactive check-in configuration. Absent fields are left unchanged. Enabling syncs the kind:checkin automation job onto the scheduler; disabling stops it.", "tags": [ "checkin" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string" }, "deliveryChannel": { "type": "string" }, "quietHours": { "type": "string" } }, "required": [ "enabled", "cadence", "deliveryChannel", "quietHours" ], "additionalProperties": false } }, "required": [ "config" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:checkin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string" }, "deliveryChannel": { "type": "string" }, "quietHours": { "type": "string" } }, "additionalProperties": false } } } } } }, "/api/checkin/receipts": { "get": { "operationId": "checkin.receipts.list", "summary": "List Check-in Receipts", "description": "Return the visible receipts of past check-in runs (newest first): each run records whether it stayed quiet, delivered a message (and what), or was skipped.", "tags": [ "checkin" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ranAt": { "type": "number" }, "trigger": { "type": "string", "enum": [ "scheduled", "manual" ] }, "outcome": { "type": "string", "enum": [ "delivered", "quiet", "skipped-disabled", "skipped-quiet-hours", "error" ] }, "briefingSummary": { "type": "string" }, "decisionReason": { "type": "string" }, "deliveredMessage": { "type": "string" }, "deliveryChannel": { "type": "string" }, "deliveryId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "ranAt", "trigger", "outcome", "briefingSummary" ], "additionalProperties": false } } }, "required": [ "receipts" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:checkin" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/checkin/run": { "post": { "operationId": "checkin.run", "summary": "Run Check-in Now", "description": "Trigger one check-in evaluation immediately (a manual run): assemble the briefing, judge whether to contact the user, deliver if so, and record a receipt.", "tags": [ "checkin" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "delivered", "quiet", "skipped", "error" ] }, "summary": { "type": "string" }, "deliveryId": { "type": "string" } }, "required": [ "outcome", "summary" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:checkin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/ci/status": { "post": { "operationId": "ci.status", "summary": "CI Per-Job Status", "description": "Poll GitHub for a repo/ref/PR and return EVERY job with its conclusion. The overall verdict is derived from the per-job conclusions (never a rollup); continue-on-error jobs are surfaced as violations and force the verdict off \"passed\".", "tags": [ "ci" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "object", "properties": { "repo": { "type": "string" }, "ref": { "type": "string" }, "prNumber": { "type": "number" }, "overall": { "type": "string", "enum": [ "passed", "failed", "pending", "unknown" ] }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed" ] }, "conclusion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "continueOnError": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "name", "status", "conclusion" ], "additionalProperties": false } }, "violations": { "type": "array", "items": { "type": "string" } }, "checkedAt": { "type": "number" } }, "required": [ "repo", "overall", "jobs", "violations", "checkedAt" ], "additionalProperties": false } }, "required": [ "report" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:ci" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string" }, "ref": { "type": "string" }, "prNumber": { "type": "number" } }, "required": [ "repo" ], "additionalProperties": false } } } } } }, "/api/ci/watches": { "post": { "operationId": "ci.watches.create", "summary": "Create CI Watch", "description": "Create a standing watch on a repo/ref or PR. On transition to a terminal verdict it notifies the delivery channel; set triggerFixSession to opt in to starting a fix-session pre-briefed with the failing jobs on failure.", "tags": [ "ci" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "watch": { "type": "object", "properties": { "id": { "type": "string" }, "repo": { "type": "string" }, "ref": { "type": "string" }, "prNumber": { "type": "number" }, "deliveryChannel": { "type": "string" }, "triggerFixSession": { "type": "boolean" }, "lastOverall": { "type": "string", "enum": [ "passed", "failed", "pending", "unknown" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "repo", "deliveryChannel", "triggerFixSession", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "watch" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:ci" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string" }, "ref": { "type": "string" }, "prNumber": { "type": "number" }, "deliveryChannel": { "type": "string" }, "triggerFixSession": { "type": "boolean" } }, "required": [ "repo", "deliveryChannel" ], "additionalProperties": false } } } } }, "get": { "operationId": "ci.watches.list", "summary": "List CI Watches", "description": "Return every standing CI watch (repo/ref/PR, delivery channel, and whether a fix-session is opted in on failure).", "tags": [ "ci" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "watches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "repo": { "type": "string" }, "ref": { "type": "string" }, "prNumber": { "type": "number" }, "deliveryChannel": { "type": "string" }, "triggerFixSession": { "type": "boolean" }, "lastOverall": { "type": "string", "enum": [ "passed", "failed", "pending", "unknown" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "repo", "deliveryChannel", "triggerFixSession", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "watches" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:ci" ] } }, "/api/ci/watches/{watchId}": { "delete": { "operationId": "ci.watches.delete", "summary": "Delete CI Watch", "description": "Remove a standing CI watch. Returns { deleted: false } when no watch with that id existed.", "tags": [ "ci" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "watchId": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "watchId", "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:ci" ], "x-dangerous": true, "parameters": [ { "name": "watchId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/ci/watches/{watchId}/run": { "post": { "operationId": "ci.watches.run", "summary": "Check CI Watch Now", "description": "Poll a standing watch immediately: returns the per-job report, whether a completion notification fired, and whether an opted-in fix-session was triggered on failure.", "tags": [ "ci" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "object", "properties": { "repo": { "type": "string" }, "ref": { "type": "string" }, "prNumber": { "type": "number" }, "overall": { "type": "string", "enum": [ "passed", "failed", "pending", "unknown" ] }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed" ] }, "conclusion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "continueOnError": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "name", "status", "conclusion" ], "additionalProperties": false } }, "violations": { "type": "array", "items": { "type": "string" } }, "checkedAt": { "type": "number" } }, "required": [ "repo", "overall", "jobs", "violations", "checkedAt" ], "additionalProperties": false }, "notified": { "type": "boolean" }, "notificationId": { "type": "string" }, "fixSessionTriggered": { "type": "boolean" }, "fixSessionId": { "type": "string" }, "fixSessionError": { "type": "string" }, "fixSessionOffered": { "type": "boolean" }, "retired": { "type": "boolean" } }, "required": [ "report", "notified", "fixSessionTriggered" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:ci" ], "parameters": [ { "name": "watchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watchId": { "type": "string" } }, "required": [ "watchId" ], "additionalProperties": false } } } } } }, "/api/companion/chat/sessions/{sessionId}/events": { "get": { "operationId": "companion.chat.events.stream", "summary": "Stream Companion Chat Events", "description": "Server-Sent Events stream of turn and agent events scoped to a single companion-chat session.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/companion/chat/sessions/{sessionId}/messages": { "post": { "operationId": "companion.chat.messages.create", "summary": "Send Companion Chat Message", "description": "Post a user message to a companion-chat session. Accepts either `body` or `content` in the payload; `body` wins when both are provided. Attachments reference artifacts created through `artifacts.create`.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string" } }, "required": [ "messageId" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "body": { "type": "string" }, "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "artifactId": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "artifactId" ], "additionalProperties": false } }, "metadata": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "sessionId" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ], "additionalProperties": true }, { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": true }, { "type": "object", "properties": { "attachments": { "type": "array", "items": { "type": "object", "properties": { "artifactId": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "artifactId" ], "additionalProperties": false } } }, "required": [ "attachments" ], "additionalProperties": true } ] } } } } }, "get": { "operationId": "companion.chat.messages.list", "summary": "List Companion Chat Messages", "description": "Return the message list for a companion-chat session.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "artifactId", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true } }, "createdAt": { "type": "number" }, "deliveryState": { "type": "string", "enum": [ "cancelled", "queued" ] }, "inReplyTo": { "type": "string" } }, "required": [ "id", "sessionId", "role", "content", "attachments", "createdAt" ], "additionalProperties": false } } }, "required": [ "sessionId", "messages" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/companion/chat/sessions/{sessionId}/messages/edit": { "post": { "operationId": "companion.chat.messages.edit", "summary": "Edit Companion Chat Message And Branch", "description": "Edit a user message and branch the conversation from it. `messageId` (required) is the user message to edit; the edited text is passed as `body` or `content` (as message create accepts), with optional `attachments` referencing artifacts. The original message and everything after it are SUPERSEDED, retained as history, never deleted, a new user message carrying `revisionOf` back to the original is appended, and a fresh turn answers it. Returns the new message id and the superseded ids for honest lineage. Same closed/unknown-session refusals as companion.chat.messages.retry.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "editedFrom": { "type": "string" }, "messageId": { "type": "string" }, "supersededMessageIds": { "type": "array", "items": { "type": "string" } }, "turnStarted": { "type": "boolean" } }, "required": [ "sessionId", "editedFrom", "messageId", "supersededMessageIds", "turnStarted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "messageId": { "type": "string" }, "body": { "type": "string" }, "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "artifactId": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "artifactId" ], "additionalProperties": false } }, "metadata": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "sessionId", "messageId" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ], "additionalProperties": true }, { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": true }, { "type": "object", "properties": { "attachments": { "type": "array", "items": { "type": "object", "properties": { "artifactId": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "artifactId" ], "additionalProperties": false } } }, "required": [ "attachments" ], "additionalProperties": true } ] } } } } } }, "/api/companion/chat/sessions/{sessionId}/messages/retry": { "post": { "operationId": "companion.chat.messages.retry", "summary": "Regenerate Companion Chat Response", "description": "Regenerate an assistant response. Optional `messageId` targets a specific assistant message; omitted, the latest assistant response is re-run. The prior response (and any turns after it) is SUPERSEDED, kept in the message list and on disk, flagged as retained history, never deleted, then a fresh turn re-runs from the preceding user message. Returns the superseded message ids so the caller can render the honest lineage. Rejected on a closed session (409 SESSION_CLOSED) or unknown session (404 SESSION_NOT_FOUND), and with an honest machine code (409 NO_ASSISTANT_MESSAGE) when there is nothing to regenerate.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "regeneratedFrom": { "type": "string" }, "supersededMessageIds": { "type": "array", "items": { "type": "string" } }, "turnStarted": { "type": "boolean" } }, "required": [ "sessionId", "regeneratedFrom", "supersededMessageIds", "turnStarted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/companion/chat/sessions/{sessionId}/messages/steer": { "post": { "operationId": "companion.chat.messages.steer", "summary": "Steer Companion Chat (Interrupt And Send)", "description": "Send a message that runs IMMEDIATELY, interrupting the in-flight turn if one is running. The message jumps to the front of the pending-turn queue; the active turn is cancelled through the same finalization path as companion.chat.turns.cancel (any non-empty partial reply is persisted with `deliveryState: \"cancelled\"` and the terminal `turn.cancelled` event reaches every subscriber), then the steered message's turn starts. Messages queued behind an active turn keep their places behind the steer. With no turn running this behaves as an ordinary send. Accepts the same payload as companion.chat.messages.create (`body`/`content`, `attachments`, `metadata`). Returns the new message id, `steered: true`, and `cancelledTurnId` when a turn was interrupted. Ordinary sends posted while a turn is running are QUEUED (transcript-visible immediately with `deliveryState: \"queued\"`, answered in order), steer is the explicit jump-the-line verb.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "messageId": { "type": "string" }, "steered": { "type": "boolean" }, "cancelledTurnId": { "type": "string" }, "turnStarted": { "type": "boolean" } }, "required": [ "sessionId", "messageId", "steered", "turnStarted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "body": { "type": "string" }, "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "artifactId": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "artifactId" ], "additionalProperties": false } }, "metadata": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "sessionId" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ], "additionalProperties": true }, { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": true }, { "type": "object", "properties": { "attachments": { "type": "array", "items": { "type": "object", "properties": { "artifactId": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "artifactId" ], "additionalProperties": false } } }, "required": [ "attachments" ], "additionalProperties": true } ] } } } } } }, "/api/companion/chat/sessions/{sessionId}/close": { "post": { "operationId": "companion.chat.sessions.close", "summary": "Close Companion Chat Session", "description": "Close a companion-chat session (soft close). The session record and its messages are preserved in closed state and remain listable with includeClosed. Distinct from companion.chat.sessions.delete, which permanently removes the record.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "sessionId", "status" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" } }, "required": [ "sessionId" ], "additionalProperties": false } } } } } }, "/api/companion/chat/sessions": { "post": { "operationId": "companion.chat.sessions.create", "summary": "Create Companion Chat Session", "description": "Create a new companion-chat session. Optional `provider` / `model` override the registry default; `title` and `systemPrompt` are stored on the session record.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "createdAt": { "type": "number" }, "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "companion-chat" ] }, "title": { "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "closedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "messageCount": { "type": "number" } }, "required": [ "id", "kind", "title", "model", "provider", "systemPrompt", "status", "createdAt", "updatedAt", "closedAt", "messageCount" ], "additionalProperties": false } }, "required": [ "sessionId", "createdAt", "session" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "systemPrompt": { "type": "string" } }, "additionalProperties": true, "dependentRequired": { "model": [ "provider" ], "provider": [ "model" ] } } } } } }, "get": { "operationId": "companion.chat.sessions.list", "summary": "List Companion Chat Sessions", "description": "List active companion-chat sessions. Pass `includeClosed` to include recently closed sessions.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "companion-chat" ] }, "title": { "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "closedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "messageCount": { "type": "number" } }, "required": [ "id", "kind", "title", "model", "provider", "systemPrompt", "status", "createdAt", "updatedAt", "closedAt", "messageCount" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "sessions": { "type": "number" }, "active": { "type": "number" }, "closed": { "type": "number" } }, "required": [ "sessions", "active", "closed" ], "additionalProperties": false } }, "required": [ "sessions", "totals" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "includeClosed", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/companion/chat/sessions/{sessionId}": { "delete": { "operationId": "companion.chat.sessions.delete", "summary": "Delete Companion Chat Session", "description": "Permanently remove a companion-chat session: the on-disk record file is deleted and the session is dropped from the shared session store, this does NOT merely close it (use companion.chat.sessions.close for a soft close). Requires the session to already be closed: deleting a still-active session is rejected with 409 SESSION_ACTIVE (close it, then delete). An unknown or already-deleted id is a 404 SESSION_NOT_FOUND, never a 200-noop.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "sessionId", "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "get": { "operationId": "companion.chat.sessions.get", "summary": "Get Companion Chat Session", "description": "Return a companion-chat session record together with its full message history.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "companion-chat" ] }, "title": { "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "closedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "messageCount": { "type": "number" } }, "required": [ "id", "kind", "title", "model", "provider", "systemPrompt", "status", "createdAt", "updatedAt", "closedAt", "messageCount" ], "additionalProperties": false }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "artifactId", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true } }, "createdAt": { "type": "number" }, "deliveryState": { "type": "string", "enum": [ "cancelled", "queued" ] }, "inReplyTo": { "type": "string" } }, "required": [ "id", "sessionId", "role", "content", "attachments", "createdAt" ], "additionalProperties": false } } }, "required": [ "session", "messages" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "companion.chat.sessions.update", "summary": "Update Companion Chat Session", "description": "Update companion-chat session metadata, including session-local `provider` and `model`, without changing the daemon/TUI current model.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "companion-chat" ] }, "title": { "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "closedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "messageCount": { "type": "number" } }, "required": [ "id", "kind", "title", "model", "provider", "systemPrompt", "status", "createdAt", "updatedAt", "closedAt", "messageCount" ], "additionalProperties": false } }, "required": [ "session" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "title": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "systemPrompt": { "type": "string" } }, "required": [ "sessionId" ], "additionalProperties": true, "dependentRequired": { "model": [ "provider" ], "provider": [ "model" ] }, "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": true }, { "type": "object", "properties": { "model": { "type": "string" } }, "required": [ "model" ], "additionalProperties": true }, { "type": "object", "properties": { "provider": { "type": "string" } }, "required": [ "provider" ], "additionalProperties": true }, { "type": "object", "properties": { "systemPrompt": { "type": "string" } }, "required": [ "systemPrompt" ], "additionalProperties": true } ] } } } } } }, "/api/companion/chat/sessions/{sessionId}/turns/cancel": { "post": { "operationId": "companion.chat.turns.cancel", "summary": "Cancel Companion Chat Turn", "description": "Stop the in-flight turn for a companion chat session, a true server-side stop: the provider stream is aborted, any non-empty partial reply is persisted to the transcript with an explicit `deliveryState: \"cancelled\"` marker (an honest partial, never disguised as a complete reply) AND committed to the model-facing conversation history with an explicit interruption note, later turns can reason about what the user saw and stopped, which is usually what a follow-up or steer refers to, and the terminal `turn.cancelled` event is published to every subscriber of the session stream so a stop from one client converges on all others. Any announced tool call without a result is closed with a synthetic error `turn.tool_result` before the terminal event. Optional `turnId` guards against cancelling a newer turn a stale stop raced against (409 TURN_MISMATCH). No turn in flight is the benign 404 NO_ACTIVE_TURN (the turn finished before the stop landed). Repeat cancels are idempotent successes. The session stays open; the next message starts a fresh turn normally.", "tags": [ "companion" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "cancelled": { "type": "boolean" }, "alreadyCancelled": { "type": "boolean" }, "partialPersisted": { "type": "boolean" } }, "required": [ "sessionId", "turnId", "cancelled", "partialPersisted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "turnId": { "type": "string" } }, "required": [ "sessionId" ], "additionalProperties": true } } } } } }, "/config": { "get": { "operationId": "config.get", "summary": "Get Config", "description": "Return the resolved GoodVibes config snapshot.", "tags": [ "config" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "danger": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "controlPlane": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "web": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "network": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "service": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "providers": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "ui": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "channels": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "watchers": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "memory": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:config" ] }, "post": { "operationId": "config.set", "summary": "Set Config Value", "description": "Set a config value through the daemon API.", "tags": [ "config" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "key": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "persistedTo": { "type": "string" }, "tier": { "type": "string" }, "daemonOwned": { "type": "boolean" } }, "required": [ "success", "key" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:config" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ], "additionalProperties": true } } } } } }, "/config/credentials": { "get": { "operationId": "credentials.get", "summary": "Get Credential Status", "description": "Return secret-free credential status (configured/usable) for the shared store. Never returns raw secret bytes. Optional ?key= narrows to one credential.", "tags": [ "config" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "credentials": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "configured": { "type": "boolean" }, "usable": { "type": "boolean" }, "source": { "type": "string" }, "scope": { "type": "string" }, "secure": { "type": "boolean" }, "overriddenByEnv": { "type": "boolean" }, "refSource": { "type": "string" } }, "required": [ "key", "configured", "usable", "source", "scope", "secure", "overriddenByEnv" ], "additionalProperties": false } } }, "required": [ "available", "credentials" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:config" ], "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/continuity": { "get": { "operationId": "continuity.snapshot", "summary": "Continuity Snapshot", "description": "Return the continuity integration snapshot.", "tags": [ "continuity" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "status": { "type": "string" }, "recoveryState": { "type": "string" }, "lastSessionPointer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recoveryFilePresent": { "type": "boolean" }, "recoveryFile": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "timestamp": { "type": "number" }, "sessionId": { "type": "string" }, "returnContext": { "type": "object", "properties": { "activityLabel": { "type": "string" }, "statusLabel": { "type": "string" }, "lastUserPrompt": { "type": "string" }, "lastAssistantReply": { "type": "string" }, "pendingApprovals": { "type": "number" }, "toolCallCount": { "type": "number" }, "toolResultCount": { "type": "number" }, "assistantTurnCount": { "type": "number" }, "userTurnCount": { "type": "number" }, "lastRole": { "type": "string" }, "activeTasks": { "type": "number" }, "blockedTasks": { "type": "number" }, "remoteContracts": { "type": "number" }, "remoteRunners": { "type": "array", "items": { "type": "string" } }, "worktreeCount": { "type": "number" }, "worktreePaths": { "type": "array", "items": { "type": "string" } }, "openPanels": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "string" } }, "assistedNarrative": { "type": "string" } }, "required": [ "activityLabel", "statusLabel", "pendingApprovals", "toolCallCount", "toolResultCount", "assistantTurnCount", "userTurnCount", "lines" ], "additionalProperties": false } }, "required": [ "title", "timestamp", "sessionId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "sessionId", "status", "recoveryState", "lastSessionPointer", "recoveryFilePresent", "recoveryFile" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:continuity" ] } }, "/api/control-plane/auth": { "get": { "operationId": "control.auth.current", "summary": "Current Auth Context", "description": "Return the current control-plane principal, granted scopes, and authentication mode.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "authMode": { "type": "string", "enum": [ "anonymous", "invalid", "session", "shared-token" ] }, "tokenPresent": { "type": "boolean" }, "authorizationHeaderPresent": { "type": "boolean" }, "sessionCookiePresent": { "type": "boolean" }, "principalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "principalKind": { "anyOf": [ { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, { "type": "null" } ] }, "admin": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "authenticated", "authMode", "tokenPresent", "authorizationHeaderPresent", "sessionCookiePresent", "principalId", "principalKind", "admin", "scopes", "roles" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "public", "x-transport": [ "http", "ws" ], "security": [] } }, "/login": { "post": { "operationId": "control.auth.login", "summary": "Login", "description": "Authenticate a local control-plane user and create a session token.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "token": { "type": "string" }, "username": { "type": "string" }, "expiresAt": { "type": "number" } }, "required": [ "authenticated", "token", "username", "expiresAt" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "public", "x-transport": [ "http" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "username", "password" ], "additionalProperties": false } } } } } }, "/api/control-plane/clients": { "get": { "operationId": "control.clients.list", "summary": "List Control-Plane Clients", "description": "Return authenticated and recently connected control-plane clients.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "clients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "connectedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "userId": { "type": "string" } }, "required": [ "id", "surface", "label", "connectedAt", "lastSeenAt" ], "additionalProperties": false } } }, "required": [ "clients" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:control-plane" ] } }, "/api/control-plane/contract": { "get": { "operationId": "control.contract", "summary": "Operator Contract", "description": "Return the operator-facing control-plane contract manifest, including auth, transport, method, and event metadata.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contract": { "type": "object", "properties": { "version": { "type": "number" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "surface", "version" ], "additionalProperties": false }, "auth": { "type": "object", "properties": { "modes": { "type": "array", "items": { "type": "string" } }, "login": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "requestSchema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "username", "password" ], "additionalProperties": false }, "responseSchema": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "token": { "type": "string" }, "username": { "type": "string" }, "expiresAt": { "type": "number" } }, "required": [ "authenticated", "token", "username", "expiresAt" ], "additionalProperties": false } }, "required": [ "method", "path", "requestSchema", "responseSchema" ], "additionalProperties": false }, "current": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "aliasPaths": { "type": "array", "items": { "type": "string" } }, "responseSchema": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "authMode": { "type": "string", "enum": [ "anonymous", "invalid", "session", "shared-token" ] }, "tokenPresent": { "type": "boolean" }, "authorizationHeaderPresent": { "type": "boolean" }, "sessionCookiePresent": { "type": "boolean" }, "principalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "principalKind": { "anyOf": [ { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, { "type": "null" } ] }, "admin": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "authenticated", "authMode", "tokenPresent", "authorizationHeaderPresent", "sessionCookiePresent", "principalId", "principalKind", "admin", "scopes", "roles" ], "additionalProperties": false } }, "required": [ "method", "path", "responseSchema" ], "additionalProperties": false }, "sessionCookie": { "type": "object", "properties": { "name": { "type": "string" }, "httpOnly": { "type": "boolean" }, "sameSite": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "httpOnly", "sameSite", "path" ], "additionalProperties": false }, "bearer": { "type": "object", "properties": { "header": { "type": "string" }, "queryParameters": { "type": "array", "items": { "type": "string" } } }, "required": [ "header", "queryParameters" ], "additionalProperties": false } }, "required": [ "modes", "login", "current", "sessionCookie", "bearer" ], "additionalProperties": false }, "transports": { "type": "object", "properties": { "http": { "type": "object", "properties": { "statusPath": { "type": "string" }, "methodsPath": { "type": "string" }, "eventsCatalogPath": { "type": "string" } }, "required": [ "statusPath", "methodsPath", "eventsCatalogPath" ], "additionalProperties": false }, "sse": { "type": "object", "properties": { "path": { "type": "string" }, "query": { "type": "object", "properties": { "domains": { "type": "string" } }, "required": [ "domains" ], "additionalProperties": false } }, "required": [ "path", "query" ], "additionalProperties": false }, "websocket": { "type": "object", "properties": { "path": { "type": "string" }, "clientFrames": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ], "additionalProperties": false } }, "serverFrames": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ], "additionalProperties": false } } }, "required": [ "path", "clientFrames", "serverFrames" ], "additionalProperties": false } }, "required": [ "http", "sse", "websocket" ], "additionalProperties": false }, "operator": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "source": { "type": "string" }, "access": { "type": "string" }, "transport": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "http": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" } }, "required": [ "method", "path" ], "additionalProperties": false }, "events": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "outputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "pluginId": { "type": "string" }, "dangerous": { "type": "boolean" }, "invokable": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "description", "category", "source", "access", "transport", "scopes" ], "additionalProperties": false } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "source": { "type": "string" }, "transport": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "wireEvents": { "type": "array", "items": { "type": "string" } }, "outputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "pluginId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "description", "category", "source", "transport", "scopes" ], "additionalProperties": false } }, "schemaCoverage": { "type": "object", "properties": { "methods": { "type": "number" }, "typedInputs": { "type": "number" }, "genericInputs": { "type": "number" }, "typedOutputs": { "type": "number" }, "genericOutputs": { "type": "number" } }, "required": [ "methods", "typedInputs", "genericInputs", "typedOutputs", "genericOutputs" ], "additionalProperties": false }, "eventCoverage": { "type": "object", "properties": { "events": { "type": "number" }, "withDomains": { "type": "number" }, "withWireEvents": { "type": "number" } }, "required": [ "events", "withDomains", "withWireEvents" ], "additionalProperties": false }, "validationCoverage": { "type": "object", "properties": { "methods": { "type": "number" }, "validated": { "type": "number" }, "skippedGeneric": { "type": "number" }, "skippedUntyped": { "type": "number" } }, "required": [ "methods", "validated", "skippedGeneric", "skippedUntyped" ], "additionalProperties": false } }, "required": [ "methods", "events", "schemaCoverage", "eventCoverage" ], "additionalProperties": false }, "peer": { "type": "object", "properties": { "contractPath": { "type": "string" }, "relationship": { "type": "string" } }, "required": [ "contractPath", "relationship" ], "additionalProperties": false } }, "required": [ "version", "product", "auth", "transports", "operator", "peer" ], "additionalProperties": false } }, "required": [ "contract" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:control-plane" ] } }, "/api/control-plane/events/catalog": { "get": { "operationId": "control.events.catalog", "summary": "List Gateway Events", "description": "Return the event catalog for SSE and WebSocket control-plane subscriptions.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "source": { "type": "string" }, "transport": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "wireEvents": { "type": "array", "items": { "type": "string" } }, "outputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "pluginId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "description", "category", "source", "transport", "scopes" ], "additionalProperties": false } } }, "required": [ "events" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:control-plane", "read:events" ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/control-plane/events": { "get": { "operationId": "control.events.stream", "summary": "Open Control-Plane Event Stream", "description": "Open the SSE control-plane event stream.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contentType": { "type": "string" }, "mode": { "type": "string" } }, "required": [ "contentType", "mode" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http" ], "x-scopes": [ "read:events" ], "parameters": [ { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/control-plane/messages": { "get": { "operationId": "control.messages.list", "summary": "List Control-Plane Messages", "description": "Return recent surface messages published through the control plane.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "createdAt": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "level": { "type": "string", "enum": [ "info", "success", "warn", "error" ] }, "routeId": { "type": "string" }, "surfaceId": { "type": "string" }, "clientId": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "contentPath": { "type": "string" }, "contentUrl": { "type": "string" }, "dataBase64": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "artifactId", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "contentPath", "metadata" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "createdAt", "title", "body" ], "additionalProperties": false } } }, "required": [ "messages" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:control-plane" ] } }, "/api/control-plane/methods/{methodId}": { "get": { "operationId": "control.methods.get", "summary": "Get Gateway Method", "description": "Return a single gateway method descriptor.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "source": { "type": "string" }, "access": { "type": "string" }, "transport": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "http": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" } }, "required": [ "method", "path" ], "additionalProperties": false }, "events": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "outputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "pluginId": { "type": "string" }, "dangerous": { "type": "boolean" }, "invokable": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "description", "category", "source", "access", "transport", "scopes" ], "additionalProperties": false } }, "required": [ "method" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:control-plane" ], "parameters": [ { "name": "methodId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/control-plane/methods": { "get": { "operationId": "control.methods.list", "summary": "List Gateway Methods", "description": "Return the gateway method catalog.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "source": { "type": "string" }, "access": { "type": "string" }, "transport": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "http": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" } }, "required": [ "method", "path" ], "additionalProperties": false }, "events": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "outputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "pluginId": { "type": "string" }, "dangerous": { "type": "boolean" }, "invokable": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "description", "category", "source", "access", "transport", "scopes" ], "additionalProperties": false } } }, "required": [ "methods" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:control-plane" ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/control-plane": { "get": { "operationId": "control.snapshot", "summary": "Control-Plane Snapshot", "description": "Return the current control-plane gateway snapshot.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "server": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "host": { "type": "string" }, "port": { "type": "number" }, "baseUrl": { "type": "string" }, "streamingMode": { "type": "string", "enum": [ "sse", "websocket", "both" ] }, "sessionTtlMs": { "type": "number" } }, "required": [ "enabled", "host", "port", "streamingMode", "sessionTtlMs" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "clients": { "type": "number" }, "activeClients": { "type": "number" }, "surfaceMessages": { "type": "number" }, "recentEvents": { "type": "number" }, "requests": { "type": "number" }, "errors": { "type": "number" } }, "required": [ "clients", "activeClients", "surfaceMessages", "recentEvents", "requests", "errors" ], "additionalProperties": false }, "clients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "label": { "type": "string" }, "connectedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "userId": { "type": "string" } }, "required": [ "id", "surface", "label", "connectedAt", "lastSeenAt" ], "additionalProperties": false } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "surface": { "type": "string" }, "createdAt": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "level": { "type": "string", "enum": [ "info", "success", "warn", "error" ] }, "routeId": { "type": "string" }, "surfaceId": { "type": "string" }, "clientId": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "contentPath": { "type": "string" }, "contentUrl": { "type": "string" }, "dataBase64": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "artifactId", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "contentPath", "metadata" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "surface", "createdAt", "title", "body" ], "additionalProperties": false } }, "recentEvents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "createdAt": { "type": "number" }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "required": [ "id", "event", "createdAt", "payload" ], "additionalProperties": false } } }, "required": [ "server", "totals", "clients", "messages", "recentEvents" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:control-plane" ] } }, "/status": { "get": { "operationId": "control.status", "summary": "Daemon Status", "description": "Return daemon status and version. THREE version fields, because there are two versions and they are not the same number: `buildVersion` is the running artifact's own release version, what a person installed, and what the auto-update loop compares against release tags, and `platformVersion` is the SDK build it is composed from. `version` carries the build version and exists because every client already reads it; on an embedded daemon that ships no artifact of its own, all three are the platform build. Pass receipts=consume to also receive undelivered daemon receipts (update/crash/migration notices) and mark them delivered, exactly once across all consuming readers. Without the flag no receipts are returned or consumed, so identity probes and keepalives never eat them.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "buildVersion": { "type": "string" }, "platformVersion": { "type": "string" }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "at": { "type": "number" } }, "required": [ "id", "text", "at" ], "additionalProperties": false } } }, "required": [ "status", "version", "buildVersion", "platformVersion" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:control-plane" ], "parameters": [ { "name": "receipts", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "consume" ], "description": "Set to \"consume\" to receive undelivered daemon receipts and mark them delivered. Omit for a read that never consumes receipts." } } ] } }, "/api/control-plane/web": { "get": { "operationId": "control.web", "summary": "Control-Plane Web Shell", "description": "Return the built-in control-plane HTML shell for external clients.", "tags": [ "control-plane" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string" } }, "required": [ "html" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http" ], "x-scopes": [ "read:control-plane" ] } }, "/api/deliveries/{deliveryId}": { "get": { "operationId": "deliveries.get", "summary": "Get Delivery", "description": "Return a single delivery record.", "tags": [ "deliveries" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "jobId": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "dead_lettered" ] }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" }, "responseId": { "type": "string" } }, "required": [ "id", "runId", "jobId", "target", "status" ], "additionalProperties": true } }, "required": [ "delivery" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:deliveries" ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/deliveries": { "get": { "operationId": "deliveries.list", "summary": "List Deliveries", "description": "Return delivery records and integration snapshot data.", "tags": [ "deliveries" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "queued": { "type": "number" }, "started": { "type": "number" }, "succeeded": { "type": "number" }, "failed": { "type": "number" }, "deadLettered": { "type": "number" } }, "required": [ "queued", "started", "succeeded", "failed", "deadLettered" ], "additionalProperties": false }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "jobId": { "type": "string" }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "webhook", "surface", "integration", "link" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "address": { "type": "string" }, "routeId": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "dead_lettered" ] }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" }, "responseId": { "type": "string" } }, "required": [ "id", "runId", "jobId", "target", "status" ], "additionalProperties": true } } }, "required": [ "totals", "attempts" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:deliveries" ] } }, "/api/email/drafts": { "post": { "operationId": "email.draft.create", "summary": "Create Email Draft", "description": "Append a draft message to the configured IMAP Drafts folder. Distinct from the local channel draft store. Requires explicit confirmation.", "tags": [ "email" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": "string" }, "uid": { "type": "number" }, "mailbox": { "type": "string" } }, "required": [ "draftId", "mailbox" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:email" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "inReplyTo": { "type": "string" }, "references": { "type": "string" } }, "required": [ "to", "subject", "body" ], "additionalProperties": true } } } } } }, "/api/email/inbox": { "get": { "operationId": "email.inbox.list", "summary": "List Email Inbox", "description": "Return inbox message summaries fetched live from the configured IMAP account, newest first (ordered by server-assigned UID, never by the sender-written Date header). Read-only (EXAMINE / BODY.PEEK); never marks messages read. When the server answered for a message and the daemon could not read the answer, the page is short and `unreadable` says so, an omitted message is not by itself evidence that it was deleted.", "tags": [ "email" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "number" }, "from": { "type": "string" }, "subject": { "type": "string" }, "date": { "type": "string" }, "unread": { "type": "boolean" }, "bodyPreview": { "type": "string" }, "messageId": { "type": "string" } }, "required": [ "uid", "from", "subject", "date", "unread", "bodyPreview", "messageId" ], "additionalProperties": false } }, "total": { "type": "number" }, "unreadable": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "detail" ], "additionalProperties": false } } }, "required": [ "messages", "total" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:email" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "unreadOnly", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/email/inbox/{uid}": { "get": { "operationId": "email.inbox.read", "summary": "Read Email Message", "description": "Return the full body and attachment metadata for a single inbox message by IMAP UID. Read-only (BODY.PEEK; does not mark as read).", "tags": [ "email" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "number" }, "from": { "type": "string" }, "subject": { "type": "string" }, "date": { "type": "string" }, "messageId": { "type": "string" }, "bodyText": { "type": "string" }, "bodyHtml": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "number" } }, "required": [ "filename", "contentType", "sizeBytes" ], "additionalProperties": false } } }, "required": [ "uid", "from", "subject", "date", "messageId", "bodyText" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:email" ], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/email/send": { "post": { "operationId": "email.send", "summary": "Send Email", "description": "Send a composed email via the configured SMTP account. Irreversible external send; requires confirm: true and explicit user review of recipients and body.", "tags": [ "email" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string" }, "sentAt": { "type": "string" } }, "required": [ "messageId", "sentAt" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:email" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "inReplyTo": { "type": "string" }, "confirm": { "type": "boolean" } }, "required": [ "to", "subject", "body", "confirm" ], "additionalProperties": true } } } } } }, "/api/fleet/workstreams/{workstreamId}/graph": { "get": { "operationId": "fleet.graph.get", "summary": "Get Workstream Task Graph", "description": "The dependency-graph view of one workstream: nodes (id, title, state, cluster, files, merge state, blocked reason, orphaned flag, deepest-remaining-path depth, stalled tell, agent), edges (from depends on to), and the elastic-pool state (ready/running counts, at-cap, cap key + size, any spawn refusal). Surfaces render the task graph under the chain from this, the fleet/observability idiom. 404 when the workstream is unknown to this daemon.", "tags": [ "fleet" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workstreamId": { "type": "string" }, "title": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "state": { "type": "string" }, "cluster": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "mergeState": { "type": "string" }, "blockedReason": { "type": "string" }, "orphaned": { "type": "boolean" }, "remainingDepth": { "type": "number" }, "stalled": { "type": "boolean" }, "agentId": { "type": "string" } }, "required": [ "id", "title", "state", "files", "orphaned", "remainingDepth", "stalled" ], "additionalProperties": false } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false } }, "pool": { "anyOf": [ { "type": "object", "properties": { "ready": { "type": "number" }, "running": { "type": "number" }, "atCap": { "type": "boolean" }, "capKey": { "type": "string" }, "maxSize": { "type": "number" }, "refusal": { "type": "string" } }, "required": [ "ready", "running", "atCap", "capKey", "maxSize" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "workstreamId", "title", "nodes", "edges", "pool" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:fleet" ], "parameters": [ { "name": "workstreamId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/health": { "get": { "operationId": "health.snapshot", "summary": "Health Snapshot", "description": "Return the health integration snapshot.", "tags": [ "health" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "overall": { "type": "string", "enum": [ "healthy", "degraded" ] }, "degradedDomains": { "type": "array", "items": { "type": "string" } }, "providerProblems": { "type": "array", "items": { "type": "string" } }, "mcpProblems": { "type": "object", "properties": { "degraded": { "type": "array", "items": { "type": "string" } }, "quarantined": { "type": "array", "items": { "type": "string" } } }, "required": [ "degraded", "quarantined" ], "additionalProperties": false }, "integrationProblems": { "type": "array", "items": { "type": "string" } }, "network": { "type": "object", "properties": { "controlPlane": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": true } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": true }, "httpListener": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": true } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": true }, "outbound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "bundled", "bundled+custom", "custom" ] }, "allowInsecureLocalhost": { "type": "boolean" }, "customCaFile": { "type": "string" }, "customCaDir": { "type": "string" }, "customCaEntryCount": { "type": "number" }, "effectiveCaStrategy": { "type": "string", "enum": [ "bun-default", "bundled+custom", "custom" ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowInsecureLocalhost", "customCaEntryCount", "effectiveCaStrategy", "errors" ], "additionalProperties": true } }, "required": [ "controlPlane", "httpListener", "outbound" ], "additionalProperties": false } }, "required": [ "overall", "degradedDomains", "providerProblems", "mcpProblems", "integrationProblems" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:health" ] } }, "/api/ops/memory": { "get": { "operationId": "ops.memory.get", "summary": "Get Memory Governance State", "description": "The MemoryGovernor snapshot: the current memory-pressure tier and budget, resident set size and heap, per-cache footprints the governor can shrink, which deferrable background jobs are paused, and the leak-tripwire state. Read-only observability so operators can see the daemon shedding memory before it approaches OOM.", "tags": [ "health" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "normal", "elevated", "high", "critical" ] }, "budgetMb": { "type": "number" }, "rssMb": { "type": "number" }, "heapUsedMb": { "type": "number" }, "heapTotalMb": { "type": "number" }, "usedPct": { "type": "number" }, "refusingExpensiveWork": { "type": "boolean" }, "caches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "entries": { "type": "number" }, "estimatedBytes": { "type": "number" } }, "required": [ "id", "name", "entries" ], "additionalProperties": false } }, "pausedJobs": { "type": "array", "items": { "type": "string" } }, "tripwire": { "type": "object", "properties": { "armed": { "type": "boolean" }, "sustainedSec": { "type": "number" }, "rateMbPerSec": { "type": "number" } }, "required": [ "armed", "sustainedSec", "rateMbPerSec" ], "additionalProperties": false }, "thresholds": { "type": "object", "properties": { "elevatedPct": { "type": "number" }, "highPct": { "type": "number" }, "criticalPct": { "type": "number" } }, "required": [ "elevatedPct", "highPct", "criticalPct" ], "additionalProperties": false } }, "required": [ "tier", "budgetMb", "rssMb", "heapUsedMb", "usedPct", "refusingExpensiveWork", "caches", "pausedJobs", "tripwire", "thresholds" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:health" ] } }, "/api/power/keep-awake": { "post": { "operationId": "power.keepAwake.set", "summary": "Set the Owner Keep-Awake Toggle", "description": "Turn the owner keep-awake toggle on or off: a daemon-held sleep inhibitor INDEPENDENT of work state, surviving surface closes, persisted as power.keepAwake. Covers idle + sleep + lid-switch classes where grantable; the returned state names any refused class honestly. No timers, no AC-only sub-options, the always-visible chip is the safety mechanism. Emits runtime.ops OPS_POWER_STATE_CHANGED so every attached surface updates its chip.", "tags": [ "health" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "work": { "type": "object", "properties": { "held": { "type": "boolean" }, "grantedClasses": { "type": "array", "items": { "type": "string", "enum": [ "handle-lid-switch", "idle", "sleep" ] } }, "deniedClasses": { "type": "array", "items": { "type": "string", "enum": [ "handle-lid-switch", "idle", "sleep" ] } }, "reasons": { "type": "array", "items": { "type": "string" } }, "heldSince": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "capMinutes": { "type": "number" }, "capExpiresAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "capExpired": { "type": "boolean" } }, "required": [ "held", "grantedClasses", "deniedClasses", "reasons", "heldSince", "capMinutes", "capExpiresAt", "capExpired" ], "additionalProperties": false }, "keepAwake": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "held": { "type": "boolean" }, "grantedClasses": { "type": "array", "items": { "type": "string", "enum": [ "handle-lid-switch", "idle", "sleep" ] } }, "deniedClasses": { "type": "array", "items": { "type": "string", "enum": [ "handle-lid-switch", "idle", "sleep" ] } }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "enabled", "held", "grantedClasses", "deniedClasses", "note" ], "additionalProperties": false } }, "required": [ "platform", "work", "keepAwake" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:config" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } } } }, "/api/power/status": { "get": { "operationId": "power.status.get", "summary": "Get Sleep-Ownership State", "description": "The host sleep-ownership state: whether the automatic work inhibitor is held (and the live \"held because X\" reasons, cap, and expiry), and the owner keep-awake toggle with the classes the OS actually granted vs refused, a refused lid-switch block is stated honestly (\"idle sleep blocked; lid-close suspend is controlled by your OS here\"), never papered over. Surfaces render the always-visible \"sleep disabled\" chip from this state and the runtime.ops OPS_POWER_STATE_CHANGED event.", "tags": [ "health" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "work": { "type": "object", "properties": { "held": { "type": "boolean" }, "grantedClasses": { "type": "array", "items": { "type": "string", "enum": [ "handle-lid-switch", "idle", "sleep" ] } }, "deniedClasses": { "type": "array", "items": { "type": "string", "enum": [ "handle-lid-switch", "idle", "sleep" ] } }, "reasons": { "type": "array", "items": { "type": "string" } }, "heldSince": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "capMinutes": { "type": "number" }, "capExpiresAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "capExpired": { "type": "boolean" } }, "required": [ "held", "grantedClasses", "deniedClasses", "reasons", "heldSince", "capMinutes", "capExpiresAt", "capExpired" ], "additionalProperties": false }, "keepAwake": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "held": { "type": "boolean" }, "grantedClasses": { "type": "array", "items": { "type": "string", "enum": [ "handle-lid-switch", "idle", "sleep" ] } }, "deniedClasses": { "type": "array", "items": { "type": "string", "enum": [ "handle-lid-switch", "idle", "sleep" ] } }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "enabled", "held", "grantedClasses", "deniedClasses", "note" ], "additionalProperties": false } }, "required": [ "platform", "work", "keepAwake" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:health" ] } }, "/api/voice/local/install": { "post": { "operationId": "voice.local.install", "summary": "Install the Managed Local-Voice Runtime", "description": "One-act setup: download + checksum-verify the piper TTS engine, a default voice, and (where a pinned goodvibes-built bundle exists) the whisper.cpp STT engine with its default model into the goodvibes-managed directory, then point the voice.local.* config keys at the managed install, never overwriting a key you already set to a custom value (skipped keys are reported). After this, local TTS works with zero further configuration. Downloads only when you ask; a failed or checksum-mismatched download keeps nothing.", "tags": [ "health" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioned": { "type": "boolean" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tts": { "type": "object", "properties": { "engine": { "type": "string" }, "state": { "type": "string", "enum": [ "provisioned", "unsupported-platform", "download-failed", "checksum-mismatch" ] }, "binaryPath": { "type": "string" }, "modelPath": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "engine", "state" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "engine": { "type": "string" }, "state": { "type": "string", "enum": [ "provisioned", "unsupported-platform", "download-failed", "checksum-mismatch", "bundle-unavailable", "sideload-mismatch" ] }, "binaryPath": { "type": "string" }, "modelPath": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "engine", "state" ], "additionalProperties": false }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "installed", "skipped", "failed" ] }, "bytes": { "type": "number" }, "error": { "type": "string" } }, "required": [ "id", "state" ], "additionalProperties": false } }, "configured": { "type": "object", "properties": { "set": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "key", "reason" ], "additionalProperties": false } } }, "required": [ "set", "skipped" ], "additionalProperties": false } }, "required": [ "provisioned", "platform", "tts", "stt", "components", "configured" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:config" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/voice/local/status": { "get": { "operationId": "voice.local.status", "summary": "Get Managed Local-Voice Runtime State", "description": "Whether the managed local voice runtime (piper TTS + a default voice) is installed: not-provisioned (with a size-labeled offer), partial, provisioned, or unsupported-platform. STT (whisper.cpp) reports its own managed state: goodvibes builds and pins the whisper.cpp bundle per platform (no official prebuilt exists; provisioning never compiles on your machine), so where a pinned bundle exists STT provisions like TTS, and elsewhere it reports unsupported honestly. While a voice.local.install run is active, the response also carries installInProgress, the live per-component progress (phase, byte sizes where known) of that run, so surfaces poll this read during the install to render real progress; the section is absent when no install is running. Read-only.", "tags": [ "health" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "not-provisioned", "partial", "provisioned", "unsupported-platform" ] }, "tts": { "type": "object", "properties": { "engine": { "type": "string" }, "binaryPresent": { "type": "boolean" }, "voicePresent": { "type": "boolean" }, "binaryPath": { "type": "string" }, "modelPath": { "type": "string" } }, "required": [ "engine", "binaryPresent", "voicePresent", "binaryPath", "modelPath" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "engine": { "type": "string" }, "supported": { "type": "boolean" }, "state": { "type": "string", "enum": [ "not-provisioned", "partial", "provisioned", "unsupported-platform" ] }, "binaryPresent": { "type": "boolean" }, "modelPresent": { "type": "boolean" }, "binaryPath": { "type": "string" }, "modelPath": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "engine", "supported", "state", "binaryPresent", "modelPresent", "binaryPath", "modelPath" ], "additionalProperties": false }, "offerBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "installInProgress": { "type": "object", "properties": { "startedAt": { "type": "number" }, "components": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string" }, "phase": { "type": "string", "enum": [ "skip", "download", "verify", "extract", "done", "error" ] }, "message": { "type": "string" }, "bytesTotal": { "type": "number" }, "bytesDone": { "type": "number" } }, "required": [ "component", "phase" ], "additionalProperties": false } } }, "required": [ "startedAt", "components" ], "additionalProperties": false } }, "required": [ "platform", "state", "tts", "stt", "offerBytes" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:health" ] } }, "/api/voice/wake/model": { "get": { "operationId": "voice.wake.model.get", "summary": "Read Wake-Word Model Bytes", "description": "Read one provisioned wake artifact in bounded chunks, for a surface that cannot fetch it itself, a browser tab, whose cross-origin fetch of the release asset is refused because that asset answers with no CORS header. Each chunk carries the offset, the whole artifact's size, and its PINNED sha256, so a client reassembles the file and verifies it against the pin: a truncated transfer fails at the consumer instead of loading as a model that silently never detects. Both classifier formats are served, \"classifier\" is the onnx build a browser tab loads, \"tflite\" the same classifier for a runtime that cannot, as is the speech gate voice.wake.vadThreshold runs (\"vad\"), and so is the attribution NOTICE of each redistributable artifact (\"notice\" for the classifier, \"embedding-notice\" for the front end, \"vad-notice\" for the gate), because a client that can fetch the bytes but not the NOTICE cannot satisfy the terms it received them under. Serves what is on disk and does not download; installation puts it there, and voice.wake.provision is the recovery path when it is missing.", "tags": [ "health" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "component": { "type": "string", "enum": [ "classifier", "tflite", "embedding", "notice", "embedding-notice", "vad", "vad-notice" ] }, "offset": { "type": "number" }, "bytes": { "type": "number" }, "totalBytes": { "type": "number" }, "sha256": { "type": "string" }, "dataBase64": { "type": "string" }, "complete": { "type": "boolean" } }, "required": [ "component", "offset", "bytes", "totalBytes", "sha256", "dataBase64", "complete" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:health" ], "parameters": [ { "name": "component", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "classifier", "tflite", "embedding", "notice", "embedding-notice", "vad", "vad-notice" ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "maxBytes", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/voice/wake/provision": { "post": { "operationId": "voice.wake.provision", "summary": "Download the Wake-Word Models", "description": "Download and checksum-verify the pinned wake-word classifier in both runtime formats (onnx and tflite), the speech-embedding front end, the speech gate voice.wake.vadThreshold runs, and the attribution NOTICE of each, into the goodvibes-managed directory, about 6.1 MB. Installing goodvibes already does this, and a daemon retries at boot, so this verb is the RECOVERY path: an install that was offline, an artifact that failed verification, or a re-provision after the pinned model changes. Resumable by re-running: an artifact that already matches its pin is skipped, and one that is present but fails verification is replaced rather than used. A failed or mismatched download keeps nothing at the destination. Single-flight: two surfaces asking at once, or a boot attempt and a user asking, join one download instead of racing for the same files.", "tags": [ "health" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "mobileFormatReady": { "type": "boolean" }, "vadReady": { "type": "boolean" }, "modelVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "noticePath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "embeddingNoticePath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recallIsSyntheticOnly": { "type": "boolean" }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string", "enum": [ "classifier", "mobile-classifier", "notice", "embedding", "embedding-notice", "vad", "vad-notice" ] }, "state": { "type": "string", "enum": [ "installed", "skipped", "failed" ] }, "path": { "type": "string" }, "bytes": { "type": "number" }, "error": { "type": "string" } }, "required": [ "component", "state", "path" ], "additionalProperties": false } } }, "required": [ "ready", "mobileFormatReady", "vadReady", "modelVersion", "noticePath", "embeddingNoticePath", "recallIsSyntheticOnly", "outcomes" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:config" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/voice/wake/status": { "get": { "operationId": "voice.wake.status", "summary": "Get Wake-Word Model State", "description": "Whether the pinned wake-word artifacts are on disk and VERIFIED BY CONTENT: the \"hey goodvibes\" classifier, the tflite form of the same classifier, the speech-embedding front end the classifier sits behind, the speech gate voice.wake.vadThreshold runs, and the attribution NOTICE belonging to each of the three redistributable artifacts (the classifier's, the front end's and the gate's). Each reports verified, corrupt (present but failing its checksum, a truncated or swapped file, distinct from missing) and its byte size, with the total a fresh provision would download. Installing goodvibes provisions these, and a daemon retries at boot whatever the install could not fetch, so on a normal machine this reads ready without anyone having run a setup command; an offline install reports not-provisioned here until it is retried. The overall ready flag covers the classifier, the front end and both of THEIR NOTICEs, an artifact whose attribution is missing is not one this daemon may serve, and excludes two things: the tflite twin, which nothing here loads, so a host missing just that can still detect; and the speech gate, reported as vadReady instead, because voice.wake.vadThreshold defaults to 0 and the detector runs without it. Also restates that the model's published recall figures are measured on synthesised speech only, which any surface describing the model must carry. Never downloads. Read-only.", "tags": [ "health" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "classifier": { "type": "object", "properties": { "path": { "type": "string" }, "verified": { "type": "boolean" }, "corrupt": { "type": "boolean" }, "bytes": { "type": "number" } }, "required": [ "path", "verified", "corrupt", "bytes" ], "additionalProperties": false }, "mobileClassifier": { "type": "object", "properties": { "path": { "type": "string" }, "verified": { "type": "boolean" }, "corrupt": { "type": "boolean" }, "bytes": { "type": "number" } }, "required": [ "path", "verified", "corrupt", "bytes" ], "additionalProperties": false }, "notice": { "type": "object", "properties": { "path": { "type": "string" }, "verified": { "type": "boolean" }, "corrupt": { "type": "boolean" }, "bytes": { "type": "number" } }, "required": [ "path", "verified", "corrupt", "bytes" ], "additionalProperties": false }, "embedding": { "type": "object", "properties": { "path": { "type": "string" }, "verified": { "type": "boolean" }, "corrupt": { "type": "boolean" }, "bytes": { "type": "number" } }, "required": [ "path", "verified", "corrupt", "bytes" ], "additionalProperties": false }, "embeddingNotice": { "type": "object", "properties": { "path": { "type": "string" }, "verified": { "type": "boolean" }, "corrupt": { "type": "boolean" }, "bytes": { "type": "number" } }, "required": [ "path", "verified", "corrupt", "bytes" ], "additionalProperties": false }, "vad": { "type": "object", "properties": { "path": { "type": "string" }, "verified": { "type": "boolean" }, "corrupt": { "type": "boolean" }, "bytes": { "type": "number" } }, "required": [ "path", "verified", "corrupt", "bytes" ], "additionalProperties": false }, "vadNotice": { "type": "object", "properties": { "path": { "type": "string" }, "verified": { "type": "boolean" }, "corrupt": { "type": "boolean" }, "bytes": { "type": "number" } }, "required": [ "path", "verified", "corrupt", "bytes" ], "additionalProperties": false }, "vadReady": { "type": "boolean" }, "downloadBytes": { "type": "number" }, "modelVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recallIsSyntheticOnly": { "type": "boolean" } }, "required": [ "ready", "reason", "classifier", "mobileClassifier", "notice", "embedding", "embeddingNotice", "vad", "vadNotice", "vadReady", "downloadBytes", "modelVersion", "recallIsSyntheticOnly" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:health" ] } }, "/api/intelligence": { "get": { "operationId": "intelligence.snapshot", "summary": "Intelligence Snapshot", "description": "Return the intelligence integration snapshot.", "tags": [ "intelligence" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "diagnosticsStatus": { "type": "string" }, "symbolSearchStatus": { "type": "string" }, "completionsStatus": { "type": "string" }, "hoverStatus": { "type": "string" }, "errorCount": { "type": "number" }, "warningCount": { "type": "number" }, "totalRequests": { "type": "number" }, "avgLatencyMs": { "type": "number" } }, "required": [ "diagnosticsStatus", "symbolSearchStatus", "completionsStatus", "hoverStatus", "errorCount", "warningCount", "totalRequests", "avgLatencyMs" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:intelligence" ] } }, "/api/homeassistant/home-graph/ask": { "post": { "operationId": "homeassistant.homeGraph.askHomeGraph", "summary": "Ask Home Graph", "description": "Search a Home Graph knowledge space and return a source-backed answer.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "query": { "type": "string" }, "answer": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "results": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } } }, "required": [ "ok", "spaceId", "query", "answer", "results" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "query": { "type": "string" }, "limit": { "type": "number" }, "mode": { "type": "string" }, "includeSources": { "type": "boolean" }, "includeConfidence": { "type": "boolean" }, "includeLinkedObjects": { "type": "boolean" }, "timeoutMs": { "type": "number" } }, "required": [ "query" ], "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/browse": { "get": { "operationId": "homeassistant.homeGraph.browse", "summary": "Browse Home Graph", "description": "Return namespace-filtered Home Graph sources, nodes, edges, and issues.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "ok", "spaceId", "nodes", "edges", "sources", "issues" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "installationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/homeassistant/home-graph/export": { "post": { "operationId": "homeassistant.homeGraph.export", "summary": "Export Home Graph Space", "description": "Export a complete Home Graph knowledge space.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "exportedAt": { "type": "number" }, "spaceId": { "type": "string" }, "installationId": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "extractions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "artifactId": { "type": "string" }, "extractorId": { "type": "string" }, "format": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "excerpt": { "type": "string" }, "sections": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } }, "estimatedTokens": { "type": "number" }, "structure": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "sourceId", "extractorId", "format", "sections", "links", "estimatedTokens", "structure", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "version", "exportedAt", "spaceId", "installationId", "sources", "nodes", "edges", "issues", "extractions" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/packet": { "post": { "operationId": "homeassistant.homeGraph.generateHomeGraphPacket", "summary": "Generate Home Graph Packet", "description": "Render a scoped Home Graph packet with SDK-owned inclusion/exclusion profile rules.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "title": { "type": "string" }, "markdown": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "linked": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "artifact": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "ok", "spaceId", "title", "markdown", "artifact" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "packetKind": { "type": "string" }, "title": { "type": "string" }, "sharingProfile": { "type": "string" }, "includeFields": { "type": "array", "items": { "type": "string" } }, "excludeFields": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/room-page": { "post": { "operationId": "homeassistant.homeGraph.generateRoomPage", "summary": "Generate Room Page", "description": "Render a Home Graph room/area page and materialize it as markdown.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "title": { "type": "string" }, "markdown": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "linked": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "artifact": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "ok", "spaceId", "title", "markdown", "artifact" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "areaId": { "type": "string" }, "roomId": { "type": "string" }, "title": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/import": { "post": { "operationId": "homeassistant.homeGraph.import", "summary": "Import Home Graph Space", "description": "Restore a Home Graph knowledge space export into the current daemon knowledge store.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "imported": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "ok", "spaceId", "imported" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "data": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "data" ], "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/ingest/artifact": { "post": { "operationId": "homeassistant.homeGraph.ingestHomeGraphArtifact", "summary": "Ingest Home Graph Artifact", "description": "Index an existing artifact reference, JSON path/URI reference, multipart file upload, or raw binary upload as a Home Graph document, receipt, warranty, manual, or photo.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "artifactId": { "type": "string" }, "extraction": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "artifactId": { "type": "string" }, "extractorId": { "type": "string" }, "format": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "excerpt": { "type": "string" }, "sections": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } }, "estimatedTokens": { "type": "number" }, "structure": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "sourceId", "extractorId", "format", "sections", "links", "estimatedTokens", "structure", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "linked": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "spaceId", "source" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "artifactId": { "type": "string" }, "path": { "type": "string" }, "uri": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "target": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "allowPrivateHosts": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "artifactId": { "type": "string" } }, "required": [ "artifactId" ], "additionalProperties": true }, { "type": "object", "properties": { "path": { "type": "string" } }, "required": [ "path" ], "additionalProperties": true }, { "type": "object", "properties": { "uri": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": true } ] } } } } } }, "/api/homeassistant/home-graph/ingest/note": { "post": { "operationId": "homeassistant.homeGraph.ingestHomeGraphNote", "summary": "Ingest Home Graph Note", "description": "Store a Home Assistant note or remember-this fact as a Home Graph source.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "artifactId": { "type": "string" }, "extraction": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "artifactId": { "type": "string" }, "extractorId": { "type": "string" }, "format": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "excerpt": { "type": "string" }, "sections": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } }, "estimatedTokens": { "type": "number" }, "structure": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "sourceId", "extractorId", "format", "sections", "links", "estimatedTokens", "structure", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "linked": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "spaceId", "source" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "target": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "body" ], "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/ingest/url": { "post": { "operationId": "homeassistant.homeGraph.ingestHomeGraphUrl", "summary": "Ingest Home Graph URL", "description": "Fetch and index a URL as a Home Graph source without writing to the default knowledge space.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "artifactId": { "type": "string" }, "extraction": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "artifactId": { "type": "string" }, "extractorId": { "type": "string" }, "format": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "excerpt": { "type": "string" }, "sections": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } }, "estimatedTokens": { "type": "number" }, "structure": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "sourceId", "extractorId", "format", "sections", "links", "estimatedTokens", "structure", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "linked": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "spaceId", "source" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "target": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "allowPrivateHosts": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "url" ], "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/link": { "post": { "operationId": "homeassistant.homeGraph.linkHomeGraphKnowledge", "summary": "Link Home Graph Knowledge", "description": "Attach a Home Graph source or node to a Home Assistant object.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "edge": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "target": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "ok", "spaceId", "edge" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "target": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "relation": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "target" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "sourceId": { "type": "string" } }, "required": [ "sourceId" ], "additionalProperties": true }, { "type": "object", "properties": { "nodeId": { "type": "string" } }, "required": [ "nodeId" ], "additionalProperties": true } ] } } } } } }, "/api/homeassistant/home-graph/issues": { "get": { "operationId": "homeassistant.homeGraph.listHomeGraphIssues", "summary": "List Home Graph Issues", "description": "Return Home Graph data quality, review, and maintenance issues.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "ok", "spaceId", "issues" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "installationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/homeassistant/home-graph/map": { "post": { "operationId": "homeassistant.homeGraph.map", "summary": "Map Home Graph", "description": "Return a visual Home Graph node/edge map with deterministic layout data and SVG.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "title": { "type": "string" }, "generatedAt": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "nodeCount": { "type": "number" }, "edgeCount": { "type": "number" }, "totalNodeCount": { "type": "number" }, "totalEdgeCount": { "type": "number" }, "facets": { "type": "object", "properties": { "recordKinds": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "nodeKinds": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "sourceTypes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "sourceStatuses": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "nodeStatuses": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "issueCodes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "issueStatuses": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "issueSeverities": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "edgeRelations": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "homeAssistant": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } } } }, "additionalProperties": true }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "recordKind": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "radius": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "recordKind", "kind", "title", "x", "y", "radius", "metadata" ], "additionalProperties": true } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fromId": { "type": "string" }, "toId": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "fromTitle": { "type": "string" }, "toTitle": { "type": "string" }, "sourceTitle": { "type": "string" }, "targetTitle": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "fromId", "toId", "relation", "weight", "metadata" ], "additionalProperties": true } }, "svg": { "type": "string" } }, "required": [ "ok", "title", "generatedAt", "width", "height", "nodeCount", "edgeCount", "nodes", "edges", "svg" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "limit": { "type": "number" }, "includeSources": { "type": "boolean" }, "includeIssues": { "type": "boolean" }, "includeGenerated": { "type": "boolean" }, "query": { "type": "string" }, "recordKinds": { "type": "array", "items": { "type": "string" } }, "ids": { "type": "array", "items": { "type": "string" } }, "linkedToIds": { "type": "array", "items": { "type": "string" } }, "nodeKinds": { "type": "array", "items": { "type": "string" } }, "sourceTypes": { "type": "array", "items": { "type": "string" } }, "sourceStatuses": { "type": "array", "items": { "type": "string" } }, "nodeStatuses": { "type": "array", "items": { "type": "string" } }, "issueCodes": { "type": "array", "items": { "type": "string" } }, "issueStatuses": { "type": "array", "items": { "type": "string" } }, "issueSeverities": { "type": "array", "items": { "type": "string" } }, "edgeRelations": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "minConfidence": { "type": "number" }, "objectKinds": { "type": "array", "items": { "type": "string" } }, "entityIds": { "type": "array", "items": { "type": "string" } }, "deviceIds": { "type": "array", "items": { "type": "string" } }, "areaIds": { "type": "array", "items": { "type": "string" } }, "integrationIds": { "type": "array", "items": { "type": "string" } }, "integrationDomains": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "deviceClasses": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "string" } }, "ha": { "type": "object", "properties": { "objectKinds": { "type": "array", "items": { "type": "string" } }, "entityIds": { "type": "array", "items": { "type": "string" } }, "deviceIds": { "type": "array", "items": { "type": "string" } }, "areaIds": { "type": "array", "items": { "type": "string" } }, "integrationIds": { "type": "array", "items": { "type": "string" } }, "integrationDomains": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "deviceClasses": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false } } } } } }, "/api/homeassistant/home-graph/pages": { "get": { "operationId": "homeassistant.homeGraph.pages.list", "summary": "List Home Graph Pages", "description": "Return generated Home Graph wiki pages with optional markdown content.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "pages": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } } }, "required": [ "ok", "spaceId", "pages" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "installationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "includeMarkdown", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/homeassistant/home-graph/refinement/run": { "post": { "operationId": "homeassistant.homeGraph.refinement.run", "summary": "Run Home Graph Refinement", "description": "Run source-backed Home Graph self-improvement for a space, source list, or specific gaps.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "result": { "type": "object", "properties": { "scannedGaps": { "type": "number" }, "candidateGaps": { "type": "number" }, "processedGaps": { "type": "number" }, "createdGaps": { "type": "number" }, "repairableGaps": { "type": "number" }, "suppressedGaps": { "type": "number" }, "skippedGaps": { "type": "number" }, "searched": { "type": "number" }, "ingestedSources": { "type": "number" }, "linkedRepairs": { "type": "number" }, "blockedGaps": { "type": "number" }, "closedGaps": { "type": "number" }, "queuedTasks": { "type": "number" }, "requestedLimit": { "type": "number" }, "effectiveLimit": { "type": "number" }, "coalesced": { "type": "boolean" }, "truncated": { "type": "boolean" }, "budgetExhausted": { "type": "boolean" }, "taskIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } } }, "required": [ "scannedGaps", "createdGaps", "repairableGaps", "suppressedGaps", "skippedGaps", "searched", "ingestedSources", "linkedRepairs", "errors" ], "additionalProperties": true } }, "required": [ "ok", "spaceId", "result" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "gapIds": { "type": "array", "items": { "type": "string" } }, "sourceIds": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "number" }, "maxRunMs": { "type": "number" }, "force": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/refinement/tasks/{id}/cancel": { "post": { "operationId": "homeassistant.homeGraph.refinement.task.cancel", "summary": "Cancel Home Graph Refinement Task", "description": "Mark a queued or active Home Graph refinement task as cancelled.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "task": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "spaceId": { "type": "string" }, "subjectKind": { "type": "string" }, "subjectId": { "type": "string" }, "subjectTitle": { "type": "string" }, "subjectType": { "type": "string" }, "gapId": { "type": "string" }, "issueId": { "type": "string" }, "state": { "type": "string", "enum": [ "detected", "queued", "searching", "evaluating", "extracting", "applying", "verified", "closed", "blocked", "suppressed", "needs_review", "cancelled", "failed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "trigger": { "type": "string", "enum": [ "ingest", "homegraph-sync", "reindex", "scheduled", "answer", "manual" ] }, "budget": { "type": "object", "additionalProperties": { "type": "number" } }, "attemptCount": { "type": "number" }, "blockedReason": { "type": "string" }, "nextRepairAttemptAt": { "type": "number" }, "acceptedSourceIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "rejectedSourceUrls": { "type": "array", "items": { "type": "string" } }, "promotedFactCount": { "type": "number" }, "sourceAssessments": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "trace": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "spaceId", "state", "priority", "trigger", "budget", "attemptCount", "trace", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "ok", "spaceId", "task" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/refinement/tasks/{id}": { "get": { "operationId": "homeassistant.homeGraph.refinement.task.get", "summary": "Get Home Graph Refinement Task", "description": "Return one Home Graph refinement task and its trace.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "task": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "spaceId": { "type": "string" }, "subjectKind": { "type": "string" }, "subjectId": { "type": "string" }, "subjectTitle": { "type": "string" }, "subjectType": { "type": "string" }, "gapId": { "type": "string" }, "issueId": { "type": "string" }, "state": { "type": "string", "enum": [ "detected", "queued", "searching", "evaluating", "extracting", "applying", "verified", "closed", "blocked", "suppressed", "needs_review", "cancelled", "failed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "trigger": { "type": "string", "enum": [ "ingest", "homegraph-sync", "reindex", "scheduled", "answer", "manual" ] }, "budget": { "type": "object", "additionalProperties": { "type": "number" } }, "attemptCount": { "type": "number" }, "blockedReason": { "type": "string" }, "nextRepairAttemptAt": { "type": "number" }, "acceptedSourceIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "rejectedSourceUrls": { "type": "array", "items": { "type": "string" } }, "promotedFactCount": { "type": "number" }, "sourceAssessments": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "trace": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "spaceId", "state", "priority", "trigger", "budget", "attemptCount", "trace", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "ok", "spaceId", "task" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "installationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/homeassistant/home-graph/refinement/tasks": { "get": { "operationId": "homeassistant.homeGraph.refinement.tasks.list", "summary": "List Home Graph Refinement Tasks", "description": "Return durable Home Graph refinement tasks with states, traces, source assessments, and blocked reasons.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "spaceId": { "type": "string" }, "subjectKind": { "type": "string" }, "subjectId": { "type": "string" }, "subjectTitle": { "type": "string" }, "subjectType": { "type": "string" }, "gapId": { "type": "string" }, "issueId": { "type": "string" }, "state": { "type": "string", "enum": [ "detected", "queued", "searching", "evaluating", "extracting", "applying", "verified", "closed", "blocked", "suppressed", "needs_review", "cancelled", "failed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "trigger": { "type": "string", "enum": [ "ingest", "homegraph-sync", "reindex", "scheduled", "answer", "manual" ] }, "budget": { "type": "object", "additionalProperties": { "type": "number" } }, "attemptCount": { "type": "number" }, "blockedReason": { "type": "string" }, "nextRepairAttemptAt": { "type": "number" }, "acceptedSourceIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "rejectedSourceUrls": { "type": "array", "items": { "type": "string" } }, "promotedFactCount": { "type": "number" }, "sourceAssessments": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "trace": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "spaceId", "state", "priority", "trigger", "budget", "attemptCount", "trace", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "ok", "spaceId", "tasks" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "installationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "subjectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gapId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/homeassistant/home-graph/device-passport": { "post": { "operationId": "homeassistant.homeGraph.refreshDevicePassport", "summary": "Refresh Device Passport", "description": "Generate or refresh the living passport page for one Home Assistant device.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "title": { "type": "string" }, "markdown": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "linked": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "artifact": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "ok", "spaceId", "title", "markdown", "artifact" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "deviceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "deviceId" ], "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/reindex": { "post": { "operationId": "homeassistant.homeGraph.reindex", "summary": "Reindex Home Graph Sources", "description": "Re-extract already-stored Home Graph artifacts with missing or sparse extraction records.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "scanned": { "type": "number" }, "reparsed": { "type": "number" }, "skipped": { "type": "number" }, "failed": { "type": "number" }, "changedSourceCount": { "type": "number" }, "forcedSourceCount": { "type": "number" }, "skippedGeneratedPageArtifactCount": { "type": "number" }, "refreshedGeneratedPageCount": { "type": "number" }, "generatedPagePolicyVersion": { "type": "string" }, "coalesced": { "type": "boolean" }, "truncated": { "type": "boolean" }, "budgetExhausted": { "type": "boolean" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "failures": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "linked": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "semantic": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "generated": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "ok", "spaceId", "scanned", "reparsed", "skipped", "failed", "sources", "failures" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "limit": { "type": "number" }, "maxRunMs": { "type": "number" }, "semanticLimit": { "type": "number" }, "semanticMaxRunMs": { "type": "number" }, "generatedPageLimit": { "type": "number" }, "force": { "type": "boolean" }, "refreshPages": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/reset": { "post": { "operationId": "homeassistant.homeGraph.reset", "summary": "Reset Home Graph Space", "description": "Clear one Home Assistant Home Graph knowledge space after callers export any diagnostic backup they need.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "installationId": { "type": "string" }, "dryRun": { "type": "boolean" }, "deleted": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "artifactDeleteCandidates": { "type": "number" }, "deletedArtifacts": { "type": "number" }, "preservedArtifacts": { "type": "number" }, "artifactsDeleted": { "type": "boolean" } }, "required": [ "ok", "spaceId", "installationId", "dryRun", "deleted", "artifactDeleteCandidates", "deletedArtifacts", "preservedArtifacts", "artifactsDeleted" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "dryRun": { "type": "boolean" }, "preserveArtifacts": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/facts/review": { "post": { "operationId": "homeassistant.homeGraph.reviewHomeGraphFact", "summary": "Review Home Graph Fact", "description": "Accept, reject, resolve, edit, or forget a Home Graph issue, source, or node.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "issue": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "node": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "spaceId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "issueId": { "type": "string" }, "nodeId": { "type": "string" }, "sourceId": { "type": "string" }, "action": { "type": "string" }, "value": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "reviewer": { "type": "string" } }, "required": [ "action" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "issueId": { "type": "string" } }, "required": [ "issueId" ], "additionalProperties": true }, { "type": "object", "properties": { "nodeId": { "type": "string" } }, "required": [ "nodeId" ], "additionalProperties": true }, { "type": "object", "properties": { "sourceId": { "type": "string" } }, "required": [ "sourceId" ], "additionalProperties": true } ] } } } } } }, "/api/homeassistant/home-graph/sources": { "get": { "operationId": "homeassistant.homeGraph.sources.list", "summary": "List Home Graph Sources", "description": "Return source inventory for a Home Graph space.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "ok", "spaceId", "sources" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "installationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/homeassistant/home-graph/status": { "get": { "operationId": "homeassistant.homeGraph.status", "summary": "Home Graph Status", "description": "Return Home Assistant Home Graph status for an isolated knowledge space.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "installationId": { "type": "string" }, "sourceCount": { "type": "number" }, "nodeCount": { "type": "number" }, "edgeCount": { "type": "number" }, "issueCount": { "type": "number" }, "extractionCount": { "type": "number" }, "lastSnapshotAt": { "type": "number" }, "readiness": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "spaceId", "installationId", "sourceCount", "nodeCount", "edgeCount", "issueCount", "extractionCount", "capabilities" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "installationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/homeassistant/home-graph/sync": { "post": { "operationId": "homeassistant.homeGraph.syncHomeGraph", "summary": "Sync Home Graph", "description": "Ingest a Home Assistant registry snapshot into an isolated Home Graph knowledge space.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "installationId": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "home": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "created": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "generated": { "type": "object", "properties": { "devicePassports": { "type": "number" }, "roomPages": { "type": "number" }, "artifacts": { "type": "number" }, "sources": { "type": "number" }, "deferredDevicePassports": { "type": "number" }, "deferredRoomPages": { "type": "number" }, "truncated": { "type": "boolean" }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } } }, "required": [ "devicePassports", "roomPages", "artifacts", "sources", "errors" ], "additionalProperties": true }, "counts": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "ok", "spaceId", "installationId", "source", "home", "created", "generated", "counts" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "homeId": { "type": "string" }, "title": { "type": "string" }, "capturedAt": { "type": "number" }, "entities": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "devices": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "areas": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "automations": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "scripts": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "scenes": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "labels": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "integrations": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "helpers": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "pageAutomation": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/homeassistant/home-graph/unlink": { "post": { "operationId": "homeassistant.homeGraph.unlinkHomeGraphKnowledge", "summary": "Unlink Home Graph Knowledge", "description": "Remove an active Home Graph source/object link without deleting source history.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "edge": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "target": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "ok", "spaceId", "edge" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "target": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "relation": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "target" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "sourceId": { "type": "string" } }, "required": [ "sourceId" ], "additionalProperties": true }, { "type": "object", "properties": { "nodeId": { "type": "string" } }, "required": [ "nodeId" ], "additionalProperties": true } ] } } } } } }, "/api/knowledge/ask": { "post": { "operationId": "knowledge.ask", "summary": "Ask Knowledge", "description": "Search, semantically synthesize, and return a source-backed answer from the structured knowledge/wiki store.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "query": { "type": "string" }, "answer": { "type": "object", "properties": { "text": { "type": "string" }, "mode": { "type": "string" }, "confidence": { "type": "number" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "linkedObjects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "facts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "gaps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "synthesized": { "type": "boolean" } }, "required": [ "text", "mode", "confidence", "sources", "linkedObjects" ], "additionalProperties": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "score": { "type": "number" }, "reason": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "node": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "kind", "id", "score", "reason" ], "additionalProperties": true } } }, "required": [ "ok", "spaceId", "query", "answer", "results" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "limit": { "type": "number" }, "mode": { "type": "string" }, "includeSources": { "type": "boolean" }, "includeConfidence": { "type": "boolean" }, "includeLinkedObjects": { "type": "boolean" }, "candidateSourceIds": { "type": "array", "items": { "type": "string" } }, "candidateNodeIds": { "type": "array", "items": { "type": "string" } }, "strictCandidates": { "type": "boolean" }, "timeoutMs": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "query" ], "additionalProperties": true } } } } } }, "/api/knowledge/candidates/{id}/decide": { "post": { "operationId": "knowledge.candidate.decide", "summary": "Decide Consolidation Candidate", "description": "Accept, reject, or supersede a knowledge consolidation candidate.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidate": { "type": "object", "properties": { "id": { "type": "string" }, "candidateType": { "type": "string" }, "status": { "type": "string" }, "subjectKind": { "type": "string" }, "subjectId": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "score": { "type": "number" }, "evidence": { "type": "array", "items": { "type": "string" } }, "suggestedMemoryClass": { "type": "string" }, "suggestedScope": { "type": "string" }, "decidedAt": { "type": "number" }, "decidedBy": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "candidateType", "status", "subjectKind", "subjectId", "title", "score", "evidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "candidate" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "accept", "reject", "supersede" ] }, "decidedBy": { "type": "string" }, "reason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "decision" ], "additionalProperties": true } } } } } }, "/api/knowledge/candidates/{id}": { "get": { "operationId": "knowledge.candidate.get", "summary": "Get Consolidation Candidate", "description": "Return a single consolidation candidate.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidate": { "type": "object", "properties": { "id": { "type": "string" }, "candidateType": { "type": "string" }, "status": { "type": "string" }, "subjectKind": { "type": "string" }, "subjectId": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "score": { "type": "number" }, "evidence": { "type": "array", "items": { "type": "string" } }, "suggestedMemoryClass": { "type": "string" }, "suggestedScope": { "type": "string" }, "decidedAt": { "type": "number" }, "decidedBy": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "candidateType", "status", "subjectKind", "subjectId", "title", "score", "evidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "candidate" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/knowledge/candidates": { "get": { "operationId": "knowledge.candidates.list", "summary": "List Consolidation Candidates", "description": "Return scored consolidation candidates for durable memory promotion, review, or source refresh.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "candidateType": { "type": "string" }, "status": { "type": "string" }, "subjectKind": { "type": "string" }, "subjectId": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "score": { "type": "number" }, "evidence": { "type": "array", "items": { "type": "string" } }, "suggestedMemoryClass": { "type": "string" }, "suggestedScope": { "type": "string" }, "decidedAt": { "type": "number" }, "decidedBy": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "candidateType", "status", "subjectKind", "subjectId", "title", "score", "evidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "candidates" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "subjectKind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "subjectId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/knowledge/connectors/{id}/doctor": { "get": { "operationId": "knowledge.connector.doctor", "summary": "Doctor Knowledge Connector", "description": "Return readiness and setup diagnostics for a knowledge connector.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "object", "properties": { "connectorId": { "type": "string" }, "ready": { "type": "boolean" }, "summary": { "type": "string" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "detail": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "status", "detail" ], "additionalProperties": true } }, "hints": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "connectorId", "ready", "summary", "checks", "hints", "metadata" ], "additionalProperties": true } }, "required": [ "report" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/knowledge/connectors/{id}": { "get": { "operationId": "knowledge.connector.get", "summary": "Get Knowledge Connector", "description": "Return a single knowledge connector manifest.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connector": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "examples": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "capabilities": { "type": "array", "items": { "type": "string" } }, "setup": { "type": "object", "properties": { "version": { "type": "string" }, "summary": { "type": "string" }, "transportHints": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "path", "uri", "secret", "token", "choice" ] }, "optional": { "type": "boolean" }, "source": { "type": "string", "enum": [ "inline", "env", "goodvibes", "bitwarden", "vaultwarden", "bws", "manual" ] }, "description": { "type": "string" } }, "required": [ "key", "label", "kind" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "version", "summary" ], "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "description", "sourceType" ], "additionalProperties": true } }, "required": [ "connector" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/knowledge/connectors": { "get": { "operationId": "knowledge.connectors.list", "summary": "List Knowledge Connectors", "description": "Return discoverable knowledge ingest connectors with input metadata and examples.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "examples": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "capabilities": { "type": "array", "items": { "type": "string" } }, "setup": { "type": "object", "properties": { "version": { "type": "string" }, "summary": { "type": "string" }, "transportHints": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "path", "uri", "secret", "token", "choice" ] }, "optional": { "type": "boolean" }, "source": { "type": "string", "enum": [ "inline", "env", "goodvibes", "bitwarden", "vaultwarden", "bws", "manual" ] }, "description": { "type": "string" } }, "required": [ "key", "label", "kind" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "version", "summary" ], "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "description", "sourceType" ], "additionalProperties": true } } }, "required": [ "connectors" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ] } }, "/api/knowledge/extractions/{id}": { "get": { "operationId": "knowledge.extraction.get", "summary": "Get Knowledge Extraction", "description": "Return a single knowledge extraction record.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "extraction": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "artifactId": { "type": "string" }, "extractorId": { "type": "string" }, "format": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "excerpt": { "type": "string" }, "sections": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } }, "estimatedTokens": { "type": "number" }, "structure": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "sourceId", "extractorId", "format", "sections", "links", "estimatedTokens", "structure", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "extraction" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/knowledge/extractions": { "get": { "operationId": "knowledge.extractions.list", "summary": "List Knowledge Extractions", "description": "Return structured extraction records for ingested sources.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "extractions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "artifactId": { "type": "string" }, "extractorId": { "type": "string" }, "format": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "excerpt": { "type": "string" }, "sections": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } }, "estimatedTokens": { "type": "number" }, "structure": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "sourceId", "extractorId", "format", "sections", "links", "estimatedTokens", "structure", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "extractions" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "sourceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeAllSpaces", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/knowledge/graphql": { "post": { "operationId": "knowledge.graphql.execute", "summary": "Execute Knowledge GraphQL", "description": "Execute a GraphQL query or mutation against the dedicated knowledge domain endpoint.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "extensions": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "operationName": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "query" ], "additionalProperties": true } } } } } }, "/api/knowledge/graphql/schema": { "get": { "operationId": "knowledge.graphql.schema", "summary": "Knowledge GraphQL Schema", "description": "Return the SDL for the dedicated knowledge GraphQL endpoint.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "language": { "type": "string" }, "domain": { "type": "string" }, "schema": { "type": "string" } }, "required": [ "language", "domain", "schema" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ] } }, "/api/knowledge/ingest/artifact": { "post": { "operationId": "knowledge.ingest.artifact", "summary": "Ingest Artifact Into Knowledge", "description": "Snapshot an existing artifact, daemon-local path, remote URI, multipart file upload, or raw binary upload into the structured knowledge store and run structured extraction.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "artifactId": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "source", "issues" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "artifactId": { "type": "string" }, "path": { "type": "string" }, "uri": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sessionId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "allowPrivateHosts": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/knowledge/ingest/bookmarks": { "post": { "operationId": "knowledge.ingest.bookmarks", "summary": "Import Bookmark File", "description": "Parse a bookmark export file and ingest its URLs into the structured knowledge store.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "number" }, "failed": { "type": "number" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "imported", "failed", "sources", "errors" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "sessionId": { "type": "string" }, "allowPrivateHosts": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "path" ], "additionalProperties": true } } } } } }, "/api/knowledge/ingest/browser-history": { "post": { "operationId": "knowledge.ingest.browserHistory", "summary": "Sync Browser History Into Knowledge", "description": "Read local browser history and bookmarks and index them as metadata-first structured knowledge.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "number" }, "failed": { "type": "number" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "errors": { "type": "array", "items": { "type": "string" } }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string" }, "browser": { "type": "string" }, "profileName": { "type": "string" }, "profilePath": { "type": "string" }, "historyPath": { "type": "string" }, "bookmarksPath": { "type": "string" } }, "required": [ "family", "browser", "profileName", "profilePath" ], "additionalProperties": true } } }, "required": [ "imported", "failed", "sources", "errors", "profiles" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "number" }, "sinceMs": { "type": "number" }, "browsers": { "type": "array", "items": { "type": "string" } }, "sourceKinds": { "type": "array", "items": { "type": "string" } }, "homeOverride": { "type": "string" }, "sessionId": { "type": "string" }, "connectorId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/knowledge/ingest/connector": { "post": { "operationId": "knowledge.ingest.connector", "summary": "Ingest Connector Input", "description": "Resolve a knowledge connector against inline input, inline content, or file-backed content.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "number" }, "failed": { "type": "number" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "imported", "failed", "sources", "errors" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorId": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "content": { "type": "string" }, "path": { "type": "string" }, "sessionId": { "type": "string" }, "allowPrivateHosts": { "type": "boolean" } }, "required": [ "connectorId" ], "anyOf": [ { "required": [ "input" ] }, { "required": [ "content" ] }, { "required": [ "path" ] } ], "additionalProperties": false } } } } } }, "/api/knowledge/ingest/url": { "post": { "operationId": "knowledge.ingest.url", "summary": "Ingest URL Into Knowledge", "description": "Fetch, snapshot, and compile a URL into the structured knowledge store.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "artifactId": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "source", "issues" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "sessionId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "allowPrivateHosts": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "url" ], "additionalProperties": true } } } } } }, "/api/knowledge/ingest/urls": { "post": { "operationId": "knowledge.ingest.urls", "summary": "Import URL List", "description": "Parse a URL list file and ingest its entries into the structured knowledge store.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "number" }, "failed": { "type": "number" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "imported", "failed", "sources", "errors" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "sessionId": { "type": "string" }, "allowPrivateHosts": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "path" ], "additionalProperties": true } } } } } }, "/api/knowledge/issues/{id}/review": { "post": { "operationId": "knowledge.issue.review", "summary": "Review Knowledge Issue", "description": "Record an LLM or user review decision for a knowledge issue and optionally apply semantic facts to the linked source or node.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "issue": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "node": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "suppression": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "appliedFacts": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "ok", "issue" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string" }, "reviewer": { "type": "string" }, "value": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "action" ], "additionalProperties": false } } } } } }, "/api/knowledge/issues": { "get": { "operationId": "knowledge.issues.list", "summary": "List Knowledge Issues", "description": "Return current knowledge lint and health issues.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "issues" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeAllSpaces", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/knowledge/items/{id}": { "get": { "operationId": "knowledge.item.get", "summary": "Get Knowledge Item", "description": "Return a single structured knowledge source, node, or issue with linked relations.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "node": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "issue": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "relatedEdges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "linkedSources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "linkedNodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeAllSpaces", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/knowledge/job-runs": { "get": { "operationId": "knowledge.job-runs.list", "summary": "List Knowledge Job Runs", "description": "Return recent knowledge job runs.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "mode": { "type": "string", "enum": [ "inline", "background" ] }, "requestedAt": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "error": { "type": "string" }, "result": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": false }, { "type": "object", "properties": { "issueCount": { "type": "number" } }, "required": [ "issueCount" ], "additionalProperties": false }, { "type": "object", "properties": { "sourceCount": { "type": "number" }, "issueCount": { "type": "number" } }, "required": [ "sourceCount", "issueCount" ], "additionalProperties": false }, { "type": "object", "properties": { "refreshed": { "type": "number" } }, "required": [ "refreshed" ], "additionalProperties": false }, { "type": "object", "properties": { "imported": { "type": "number" }, "failed": { "type": "number" }, "profileCount": { "type": "number" }, "errorCount": { "type": "number" } }, "required": [ "imported", "failed", "profileCount", "errorCount" ], "additionalProperties": false }, { "type": "object", "properties": { "projections": { "type": "array", "items": { "type": "object", "properties": { "targetId": { "type": "string" }, "artifactId": { "type": "string" } }, "required": [ "targetId", "artifactId" ], "additionalProperties": false } } }, "required": [ "projections" ], "additionalProperties": false }, { "type": "object", "properties": { "scanned": { "type": "number" }, "enriched": { "type": "number" }, "skipped": { "type": "number" }, "failed": { "type": "number" }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "selfImprovement": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "scanned", "enriched", "skipped", "failed", "errors" ], "additionalProperties": true }, { "type": "object", "properties": { "scannedGaps": { "type": "number" }, "candidateGaps": { "type": "number" }, "processedGaps": { "type": "number" }, "createdGaps": { "type": "number" }, "repairableGaps": { "type": "number" }, "suppressedGaps": { "type": "number" }, "skippedGaps": { "type": "number" }, "searched": { "type": "number" }, "ingestedSources": { "type": "number" }, "linkedRepairs": { "type": "number" }, "blockedGaps": { "type": "number" }, "closedGaps": { "type": "number" }, "queuedTasks": { "type": "number" }, "requestedLimit": { "type": "number" }, "effectiveLimit": { "type": "number" }, "coalesced": { "type": "boolean" }, "truncated": { "type": "boolean" }, "budgetExhausted": { "type": "boolean" }, "taskIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } } }, "required": [ "scannedGaps", "createdGaps", "repairableGaps", "suppressedGaps", "skippedGaps", "searched", "ingestedSources", "linkedRepairs", "errors" ], "additionalProperties": true }, { "type": "object", "properties": { "reportId": { "type": "string" }, "metrics": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "reportId", "metrics" ], "additionalProperties": false } ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "jobId", "status", "mode", "requestedAt", "result", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "runs" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "jobId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/knowledge/jobs/{jobId}": { "get": { "operationId": "knowledge.job.get", "summary": "Get Knowledge Job", "description": "Return a single knowledge job definition.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "lint", "reindex", "refresh-stale", "refresh-bookmarks", "sync-browser-history", "rebuild-projections", "semantic-enrichment", "semantic-self-improvement", "light-consolidation", "deep-consolidation" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "defaultMode": { "type": "string", "enum": [ "inline", "background" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "description", "defaultMode", "metadata" ], "additionalProperties": false } }, "required": [ "job" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/knowledge/jobs/{jobId}/run": { "post": { "operationId": "knowledge.job.run", "summary": "Run Knowledge Job", "description": "Queue or run a structured knowledge maintenance job.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "mode": { "type": "string", "enum": [ "inline", "background" ] }, "requestedAt": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "error": { "type": "string" }, "result": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": false }, { "type": "object", "properties": { "issueCount": { "type": "number" } }, "required": [ "issueCount" ], "additionalProperties": false }, { "type": "object", "properties": { "sourceCount": { "type": "number" }, "issueCount": { "type": "number" } }, "required": [ "sourceCount", "issueCount" ], "additionalProperties": false }, { "type": "object", "properties": { "refreshed": { "type": "number" } }, "required": [ "refreshed" ], "additionalProperties": false }, { "type": "object", "properties": { "imported": { "type": "number" }, "failed": { "type": "number" }, "profileCount": { "type": "number" }, "errorCount": { "type": "number" } }, "required": [ "imported", "failed", "profileCount", "errorCount" ], "additionalProperties": false }, { "type": "object", "properties": { "projections": { "type": "array", "items": { "type": "object", "properties": { "targetId": { "type": "string" }, "artifactId": { "type": "string" } }, "required": [ "targetId", "artifactId" ], "additionalProperties": false } } }, "required": [ "projections" ], "additionalProperties": false }, { "type": "object", "properties": { "scanned": { "type": "number" }, "enriched": { "type": "number" }, "skipped": { "type": "number" }, "failed": { "type": "number" }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "selfImprovement": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "scanned", "enriched", "skipped", "failed", "errors" ], "additionalProperties": true }, { "type": "object", "properties": { "scannedGaps": { "type": "number" }, "candidateGaps": { "type": "number" }, "processedGaps": { "type": "number" }, "createdGaps": { "type": "number" }, "repairableGaps": { "type": "number" }, "suppressedGaps": { "type": "number" }, "skippedGaps": { "type": "number" }, "searched": { "type": "number" }, "ingestedSources": { "type": "number" }, "linkedRepairs": { "type": "number" }, "blockedGaps": { "type": "number" }, "closedGaps": { "type": "number" }, "queuedTasks": { "type": "number" }, "requestedLimit": { "type": "number" }, "effectiveLimit": { "type": "number" }, "coalesced": { "type": "boolean" }, "truncated": { "type": "boolean" }, "budgetExhausted": { "type": "boolean" }, "taskIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } } }, "required": [ "scannedGaps", "createdGaps", "repairableGaps", "suppressedGaps", "skippedGaps", "searched", "ingestedSources", "linkedRepairs", "errors" ], "additionalProperties": true }, { "type": "object", "properties": { "reportId": { "type": "string" }, "metrics": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "reportId", "metrics" ], "additionalProperties": false } ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "jobId", "status", "mode", "requestedAt", "result", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "run" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "inline", "background" ] }, "sourceIds": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "number" } }, "additionalProperties": false } } } } } }, "/api/knowledge/jobs": { "get": { "operationId": "knowledge.jobs.list", "summary": "List Knowledge Jobs", "description": "Return built-in structured knowledge maintenance jobs.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "lint", "reindex", "refresh-stale", "refresh-bookmarks", "sync-browser-history", "rebuild-projections", "semantic-enrichment", "semantic-self-improvement", "light-consolidation", "deep-consolidation" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "defaultMode": { "type": "string", "enum": [ "inline", "background" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "description", "defaultMode", "metadata" ], "additionalProperties": false } } }, "required": [ "jobs" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ] } }, "/api/knowledge/lint": { "post": { "operationId": "knowledge.lint", "summary": "Lint Structured Knowledge", "description": "Run deterministic knowledge lint checks and return the current issues.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "issues" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/knowledge/map": { "get": { "operationId": "knowledge.map", "summary": "Map Knowledge Graph", "description": "Return a deterministic visual map of structured knowledge nodes, sources, edges, and optional issues.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "spaceId": { "type": "string" }, "title": { "type": "string" }, "generatedAt": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "nodeCount": { "type": "number" }, "edgeCount": { "type": "number" }, "totalNodeCount": { "type": "number" }, "totalEdgeCount": { "type": "number" }, "facets": { "type": "object", "properties": { "recordKinds": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "nodeKinds": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "sourceTypes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "sourceStatuses": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "nodeStatuses": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "issueCodes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "issueStatuses": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "issueSeverities": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "edgeRelations": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } }, "homeAssistant": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "label": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": true } } } }, "additionalProperties": true }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "recordKind": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "radius": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "recordKind", "kind", "title", "x", "y", "radius", "metadata" ], "additionalProperties": true } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fromId": { "type": "string" }, "toId": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "fromTitle": { "type": "string" }, "toTitle": { "type": "string" }, "sourceTitle": { "type": "string" }, "targetTitle": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "fromId", "toId", "relation", "weight", "metadata" ], "additionalProperties": true } }, "svg": { "type": "string" } }, "required": [ "ok", "title", "generatedAt", "width", "height", "nodeCount", "edgeCount", "nodes", "edges", "svg" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeAllSpaces", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "includeSources", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "includeIssues", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "includeGenerated", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "recordKinds", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "linkedToIds", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "nodeKinds", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "sourceTypes", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "sourceStatuses", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "nodeStatuses", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issueCodes", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issueStatuses", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issueSeverities", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "edgeRelations", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "minConfidence", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/knowledge/nodes": { "get": { "operationId": "knowledge.nodes.list", "summary": "List Knowledge Nodes", "description": "Return compiled knowledge nodes. Without ?limit/?cursor returns { nodes: [...] } (backward compatible). With ?limit=N (1–1000, default 100) and optional ?cursor= returns a PaginatedResponse envelope { items, hasMore, nextCursor? }. Fetch cap is 5 000 items per request (knowledge store does not support cursor/offset range queries natively). Invalid cursors return HTTP 400.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "nodes" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeAllSpaces", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/knowledge/packet": { "post": { "operationId": "knowledge.packet", "summary": "Build Knowledge Packet", "description": "Build a compact structured knowledge packet for a task and write scope.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "string" }, "writeScope": { "type": "array", "items": { "type": "string" } }, "generatedAt": { "type": "number" }, "detail": { "type": "string", "enum": [ "compact", "standard", "detailed" ] }, "strategy": { "type": "string" }, "budgetLimit": { "type": "number" }, "estimatedTokens": { "type": "number" }, "truncated": { "type": "boolean" }, "totalCandidates": { "type": "number" }, "droppedCount": { "type": "number" }, "droppedForBudget": { "type": "number" }, "budgetExhausted": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "uri": { "type": "string" }, "reason": { "type": "string" }, "score": { "type": "number" }, "estimatedTokens": { "type": "number" }, "related": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind", "id", "title", "reason", "score", "estimatedTokens", "related", "evidence", "metadata" ], "additionalProperties": true } } }, "required": [ "task", "writeScope", "generatedAt", "detail", "strategy", "budgetLimit", "estimatedTokens", "truncated", "totalCandidates", "droppedCount", "droppedForBudget", "budgetExhausted", "items" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "string" }, "writeScope": { "type": "array", "items": { "type": "string" } }, "budgetLimit": { "type": "number" }, "detail": { "type": "string", "enum": [ "compact", "standard", "detailed" ] }, "knowledgeSpaceId": { "type": "string" }, "includeAllSpaces": { "type": "boolean" } }, "required": [ "task" ], "additionalProperties": true } } } } } }, "/api/knowledge/projections/materialize": { "post": { "operationId": "knowledge.projection.materialize", "summary": "Materialize Knowledge Projection", "description": "Render and persist a markdown/wiki projection as a derived artifact.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "id": { "type": "string" }, "target": { "type": "object", "properties": { "targetId": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "itemId": { "type": "string" }, "defaultPath": { "type": "string" }, "defaultFilename": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "targetId", "kind", "title", "description", "defaultPath", "defaultFilename", "metadata" ], "additionalProperties": true }, "generatedAt": { "type": "number" }, "pageCount": { "type": "number" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "title": { "type": "string" }, "format": { "type": "string" }, "content": { "type": "string" }, "itemIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "path", "title", "format", "content", "itemIds", "metadata" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "target", "generatedAt", "pageCount", "pages", "metadata" ], "additionalProperties": false }, "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "linked": { "type": "object", "properties": { "id": { "type": "string" }, "fromKind": { "type": "string" }, "fromId": { "type": "string" }, "toKind": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "weight": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "fromKind", "fromId", "toKind", "toId", "relation", "weight", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "artifactCreated": { "type": "boolean" } }, "required": [ "bundle", "artifact" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "overview", "bundle", "dashboard", "source", "node", "issue", "rollup" ] }, "id": { "type": "string" }, "limit": { "type": "number" }, "knowledgeSpaceId": { "type": "string" }, "includeAllSpaces": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "overview", "bundle", "dashboard" ] } }, "required": [ "kind" ], "additionalProperties": true }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "source", "node", "issue", "rollup" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ], "additionalProperties": true } ] } } } } } }, "/api/knowledge/projections/render": { "post": { "operationId": "knowledge.projection.render", "summary": "Render Knowledge Projection", "description": "Render a markdown/wiki projection from the canonical structured knowledge store.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "target": { "type": "object", "properties": { "targetId": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "itemId": { "type": "string" }, "defaultPath": { "type": "string" }, "defaultFilename": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "targetId", "kind", "title", "description", "defaultPath", "defaultFilename", "metadata" ], "additionalProperties": true }, "generatedAt": { "type": "number" }, "pageCount": { "type": "number" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "title": { "type": "string" }, "format": { "type": "string" }, "content": { "type": "string" }, "itemIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "path", "title", "format", "content", "itemIds", "metadata" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "target", "generatedAt", "pageCount", "pages", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "overview", "bundle", "dashboard", "source", "node", "issue", "rollup" ] }, "id": { "type": "string" }, "limit": { "type": "number" }, "knowledgeSpaceId": { "type": "string" }, "includeAllSpaces": { "type": "boolean" } }, "required": [ "kind" ], "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "overview", "bundle", "dashboard" ] } }, "required": [ "kind" ], "additionalProperties": true }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "source", "node", "issue", "rollup" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ], "additionalProperties": true } ] } } } } } }, "/api/knowledge/projections": { "get": { "operationId": "knowledge.projections.list", "summary": "List Knowledge Projections", "description": "Return renderable markdown/wiki projection targets for the knowledge domain.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "properties": { "targetId": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "itemId": { "type": "string" }, "defaultPath": { "type": "string" }, "defaultFilename": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "targetId", "kind", "title", "description", "defaultPath", "defaultFilename", "metadata" ], "additionalProperties": true } } }, "required": [ "targets" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/knowledge/refinement/run": { "post": { "operationId": "knowledge.refinement.run", "summary": "Run Knowledge Refinement", "description": "Run source-backed semantic self-improvement for a space, source list, or specific gaps.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scannedGaps": { "type": "number" }, "candidateGaps": { "type": "number" }, "processedGaps": { "type": "number" }, "createdGaps": { "type": "number" }, "repairableGaps": { "type": "number" }, "suppressedGaps": { "type": "number" }, "skippedGaps": { "type": "number" }, "searched": { "type": "number" }, "ingestedSources": { "type": "number" }, "linkedRepairs": { "type": "number" }, "blockedGaps": { "type": "number" }, "closedGaps": { "type": "number" }, "queuedTasks": { "type": "number" }, "requestedLimit": { "type": "number" }, "effectiveLimit": { "type": "number" }, "coalesced": { "type": "boolean" }, "truncated": { "type": "boolean" }, "budgetExhausted": { "type": "boolean" }, "taskIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } } }, "required": [ "scannedGaps", "createdGaps", "repairableGaps", "suppressedGaps", "skippedGaps", "searched", "ingestedSources", "linkedRepairs", "errors" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledgeSpaceId": { "type": "string" }, "spaceId": { "type": "string" }, "gapIds": { "type": "array", "items": { "type": "string" } }, "sourceIds": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "number" }, "maxRunMs": { "type": "number" }, "force": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/knowledge/refinement/tasks/{id}/cancel": { "post": { "operationId": "knowledge.refinement.task.cancel", "summary": "Cancel Knowledge Refinement Task", "description": "Mark a queued or active semantic refinement task as cancelled.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "spaceId": { "type": "string" }, "subjectKind": { "type": "string" }, "subjectId": { "type": "string" }, "subjectTitle": { "type": "string" }, "subjectType": { "type": "string" }, "gapId": { "type": "string" }, "issueId": { "type": "string" }, "state": { "type": "string", "enum": [ "detected", "queued", "searching", "evaluating", "extracting", "applying", "verified", "closed", "blocked", "suppressed", "needs_review", "cancelled", "failed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "trigger": { "type": "string", "enum": [ "ingest", "homegraph-sync", "reindex", "scheduled", "answer", "manual" ] }, "budget": { "type": "object", "additionalProperties": { "type": "number" } }, "attemptCount": { "type": "number" }, "blockedReason": { "type": "string" }, "nextRepairAttemptAt": { "type": "number" }, "acceptedSourceIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "rejectedSourceUrls": { "type": "array", "items": { "type": "string" } }, "promotedFactCount": { "type": "number" }, "sourceAssessments": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "trace": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "spaceId", "state", "priority", "trigger", "budget", "attemptCount", "trace", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "task" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": true } } } } } }, "/api/knowledge/refinement/tasks/{id}": { "get": { "operationId": "knowledge.refinement.task.get", "summary": "Get Knowledge Refinement Task", "description": "Return one semantic refinement task and its trace.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "spaceId": { "type": "string" }, "subjectKind": { "type": "string" }, "subjectId": { "type": "string" }, "subjectTitle": { "type": "string" }, "subjectType": { "type": "string" }, "gapId": { "type": "string" }, "issueId": { "type": "string" }, "state": { "type": "string", "enum": [ "detected", "queued", "searching", "evaluating", "extracting", "applying", "verified", "closed", "blocked", "suppressed", "needs_review", "cancelled", "failed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "trigger": { "type": "string", "enum": [ "ingest", "homegraph-sync", "reindex", "scheduled", "answer", "manual" ] }, "budget": { "type": "object", "additionalProperties": { "type": "number" } }, "attemptCount": { "type": "number" }, "blockedReason": { "type": "string" }, "nextRepairAttemptAt": { "type": "number" }, "acceptedSourceIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "rejectedSourceUrls": { "type": "array", "items": { "type": "string" } }, "promotedFactCount": { "type": "number" }, "sourceAssessments": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "trace": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "spaceId", "state", "priority", "trigger", "budget", "attemptCount", "trace", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "task" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/knowledge/refinement/tasks": { "get": { "operationId": "knowledge.refinement.tasks.list", "summary": "List Knowledge Refinement Tasks", "description": "Return durable semantic refinement tasks with state, traces, accepted/rejected source assessments, and blocked reasons.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "spaceId": { "type": "string" }, "subjectKind": { "type": "string" }, "subjectId": { "type": "string" }, "subjectTitle": { "type": "string" }, "subjectType": { "type": "string" }, "gapId": { "type": "string" }, "issueId": { "type": "string" }, "state": { "type": "string", "enum": [ "detected", "queued", "searching", "evaluating", "extracting", "applying", "verified", "closed", "blocked", "suppressed", "needs_review", "cancelled", "failed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "trigger": { "type": "string", "enum": [ "ingest", "homegraph-sync", "reindex", "scheduled", "answer", "manual" ] }, "budget": { "type": "object", "additionalProperties": { "type": "number" } }, "attemptCount": { "type": "number" }, "blockedReason": { "type": "string" }, "nextRepairAttemptAt": { "type": "number" }, "acceptedSourceIds": { "type": "array", "items": { "type": "string" } }, "ingestedSourceIds": { "type": "array", "items": { "type": "string" } }, "rejectedSourceUrls": { "type": "array", "items": { "type": "string" } }, "promotedFactCount": { "type": "number" }, "sourceAssessments": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "trace": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "spaceId", "state", "priority", "trigger", "budget", "attemptCount", "trace", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "tasks" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "spaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "subjectKind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "subjectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gapId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/knowledge/reindex": { "post": { "operationId": "knowledge.reindex", "summary": "Reindex Structured Knowledge", "description": "Rebuild derived knowledge relations and sync reviewed memory into the structured knowledge store.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "ready": { "type": "boolean" }, "storagePath": { "type": "string" }, "sourceCount": { "type": "number" }, "nodeCount": { "type": "number" }, "edgeCount": { "type": "number" }, "issueCount": { "type": "number" }, "extractionCount": { "type": "number" }, "jobRunCount": { "type": "number" }, "refinementTaskCount": { "type": "number" }, "usageCount": { "type": "number" }, "candidateCount": { "type": "number" }, "reportCount": { "type": "number" }, "scheduleCount": { "type": "number" } }, "required": [ "ready", "storagePath", "sourceCount", "nodeCount", "edgeCount", "issueCount", "extractionCount", "jobRunCount", "usageCount", "candidateCount", "reportCount", "scheduleCount" ], "additionalProperties": true }, "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "sourceId": { "type": "string" }, "nodeId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "severity", "code", "message", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "status", "issues" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/knowledge/reports/{id}": { "get": { "operationId": "knowledge.report.get", "summary": "Get Consolidation Report", "description": "Return a single knowledge consolidation report.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "highlights": { "type": "array", "items": { "type": "string" } }, "metrics": { "type": "object", "additionalProperties": { "type": "number" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "title", "summary", "highlights", "metrics", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "report" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/knowledge/reports": { "get": { "operationId": "knowledge.reports.list", "summary": "List Consolidation Reports", "description": "Return deterministic knowledge consolidation reports.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "highlights": { "type": "array", "items": { "type": "string" } }, "metrics": { "type": "object", "additionalProperties": { "type": "number" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "title", "summary", "highlights", "metrics", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "reports" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeAllSpaces", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/knowledge/schedules/{id}": { "delete": { "operationId": "knowledge.schedule.delete", "summary": "Delete Knowledge Schedule", "description": "Delete a managed knowledge schedule.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "get": { "operationId": "knowledge.schedule.get", "summary": "Get Knowledge Schedule", "description": "Return a single managed knowledge schedule.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "lastRunAt": { "type": "number" }, "nextRunAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "jobId", "label", "enabled", "schedule", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "schedule" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/knowledge/schedules/{id}/enabled": { "post": { "operationId": "knowledge.schedule.enable", "summary": "Set Knowledge Schedule Enabled", "description": "Enable or disable a managed knowledge schedule.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "lastRunAt": { "type": "number" }, "nextRunAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "jobId", "label", "enabled", "schedule", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "schedule" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": true } } } } } }, "/api/knowledge/schedules": { "post": { "operationId": "knowledge.schedule.save", "summary": "Save Knowledge Schedule", "description": "Create or update a managed schedule for a knowledge maintenance job.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "lastRunAt": { "type": "number" }, "nextRunAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "jobId", "label", "enabled", "schedule", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "schedule" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "interval": { "type": "string" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "interval" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "jobId", "schedule" ], "additionalProperties": true } } } } }, "get": { "operationId": "knowledge.schedules.list", "summary": "List Knowledge Schedules", "description": "Return managed schedules for background knowledge maintenance jobs.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "number" } }, "required": [ "kind", "at" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "intervalMs": { "type": "number" }, "anchorAt": { "type": "number" } }, "required": [ "kind", "intervalMs" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expression": { "type": "string" }, "timezone": { "type": "string" }, "staggerMs": { "type": "number" } }, "required": [ "kind", "expression" ], "additionalProperties": false } ] }, "lastRunAt": { "type": "number" }, "nextRunAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "jobId", "label", "enabled", "schedule", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "schedules" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/knowledge/search": { "post": { "operationId": "knowledge.search", "summary": "Search Structured Knowledge", "description": "Search structured knowledge sources and nodes with compact ranked results.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "score": { "type": "number" }, "reason": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true }, "node": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "confidence": { "type": "number" }, "sourceId": { "type": "string" }, "subject": { "type": "string" }, "subjectIds": { "type": "array", "items": { "type": "string" } }, "targetHints": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "linkedObjectIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "kind", "slug", "title", "aliases", "status", "confidence", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "kind", "id", "score", "reason" ], "additionalProperties": true } } }, "required": [ "results" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "limit": { "type": "number" }, "knowledgeSpaceId": { "type": "string" }, "includeAllSpaces": { "type": "boolean" }, "includeSources": { "type": "boolean" }, "includeNodes": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "query" ], "additionalProperties": true } } } } } }, "/api/knowledge/sources/{id}/extraction": { "get": { "operationId": "knowledge.source.extraction.get", "summary": "Get Source Extraction", "description": "Return the structured extraction record for a single knowledge source.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "extraction": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "artifactId": { "type": "string" }, "extractorId": { "type": "string" }, "format": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "excerpt": { "type": "string" }, "sections": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } }, "estimatedTokens": { "type": "number" }, "structure": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "sourceId", "extractorId", "format", "sections", "links", "estimatedTokens", "structure", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "extraction" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/knowledge/sources": { "get": { "operationId": "knowledge.sources.list", "summary": "List Knowledge Sources", "description": "Return ingested structured knowledge sources. Without ?limit/?cursor returns { sources: [...] } (backward compatible). With ?limit=N (1–1000, default 100) and optional ?cursor= returns a PaginatedResponse envelope { items, hasMore, nextCursor? }. Fetch cap is 5 000 items per request (knowledge store does not support cursor/offset range queries natively). Invalid cursors return HTTP 400.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "sources" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeAllSpaces", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/knowledge/status": { "get": { "operationId": "knowledge.status", "summary": "Knowledge Status", "description": "Return structured knowledge runtime status and record counts.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "storagePath": { "type": "string" }, "sourceCount": { "type": "number" }, "nodeCount": { "type": "number" }, "edgeCount": { "type": "number" }, "issueCount": { "type": "number" }, "extractionCount": { "type": "number" }, "jobRunCount": { "type": "number" }, "refinementTaskCount": { "type": "number" }, "usageCount": { "type": "number" }, "candidateCount": { "type": "number" }, "reportCount": { "type": "number" }, "scheduleCount": { "type": "number" } }, "required": [ "ready", "storagePath", "sourceCount", "nodeCount", "edgeCount", "issueCount", "extractionCount", "jobRunCount", "usageCount", "candidateCount", "reportCount", "scheduleCount" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeAllSpaces", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/knowledge/usage": { "get": { "operationId": "knowledge.usage.list", "summary": "List Knowledge Usage", "description": "Return the recent knowledge usage ledger for packet hits, search hits, and item inspection.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "usage": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "targetKind": { "type": "string" }, "targetId": { "type": "string" }, "usageKind": { "type": "string" }, "task": { "type": "string" }, "sessionId": { "type": "string" }, "score": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" } }, "required": [ "id", "targetKind", "targetId", "usageKind", "metadata", "createdAt" ], "additionalProperties": true } } }, "required": [ "usage" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "targetKind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "targetId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "usageKind", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/projects/planning/decisions": { "get": { "operationId": "projectPlanning.decisions.list", "summary": "List Project Decisions", "description": "Return durable decision records from the current project planning knowledge space.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "context": { "type": "string" }, "decision": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } }, "reasoning": { "type": "string" }, "consequences": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "decision" ], "additionalProperties": true } } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "decisions" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "projectPlanning.decisions.record", "summary": "Record Project Decision", "description": "Persist a meaningful project decision record for future TUI and agent context.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "decision": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "context": { "type": "string" }, "decision": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } }, "reasoning": { "type": "string" }, "consequences": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "decision" ], "additionalProperties": true }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "decision", "source" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "decision": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "context": { "type": "string" }, "decision": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } }, "reasoning": { "type": "string" }, "consequences": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "title", "decision" ], "additionalProperties": true } }, "required": [ "decision" ], "additionalProperties": true } } } } } }, "/api/projects/planning/evaluate": { "post": { "operationId": "projectPlanning.evaluate", "summary": "Evaluate Project Planning Readiness", "description": "Validate planning state and return gaps/next-question hints without mutating state or driving conversation.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "readiness": { "type": "string" }, "gaps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "message": { "type": "string" }, "question": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "whyItMatters": { "type": "string" }, "recommendedAnswer": { "type": "string" }, "consequence": { "type": "string" }, "status": { "type": "string" }, "answer": { "type": "string" }, "answeredAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "prompt" ], "additionalProperties": true }, "relatedTaskIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "severity", "message" ], "additionalProperties": true } }, "nextQuestion": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "whyItMatters": { "type": "string" }, "recommendedAnswer": { "type": "string" }, "consequence": { "type": "string" }, "status": { "type": "string" }, "answer": { "type": "string" }, "answeredAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "prompt" ], "additionalProperties": true }, "state": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "goal": { "type": "string" }, "scope": { "type": "string" }, "knownContext": { "type": "array", "items": { "type": "string" } }, "openQuestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "whyItMatters": { "type": "string" }, "recommendedAnswer": { "type": "string" }, "consequence": { "type": "string" }, "status": { "type": "string" }, "answer": { "type": "string" }, "answeredAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "prompt" ], "additionalProperties": true } }, "answeredQuestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "whyItMatters": { "type": "string" }, "recommendedAnswer": { "type": "string" }, "consequence": { "type": "string" }, "status": { "type": "string" }, "answer": { "type": "string" }, "answeredAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "prompt" ], "additionalProperties": true } }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "context": { "type": "string" }, "decision": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } }, "reasoning": { "type": "string" }, "consequences": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "decision" ], "additionalProperties": true } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "constraints": { "type": "array", "items": { "type": "string" } }, "risks": { "type": "array", "items": { "type": "string" } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "why": { "type": "string" }, "status": { "type": "string" }, "dependencies": { "type": "array", "items": { "type": "string" } }, "likelyFiles": { "type": "array", "items": { "type": "string" } }, "verification": { "type": "array", "items": { "type": "string" } }, "canRunConcurrently": { "type": "boolean" }, "needsReview": { "type": "boolean" }, "blockedOnUserInput": { "type": "boolean" }, "recommendedAgent": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title" ], "additionalProperties": true } }, "dependencies": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "verificationGates": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "agentAssignments": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "readiness": { "type": "string" }, "executionApproved": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "projectId", "knowledgeSpaceId", "goal", "knownContext", "openQuestions", "answeredQuestions", "decisions", "assumptions", "constraints", "risks", "tasks", "dependencies", "verificationGates", "agentAssignments", "readiness", "executionApproved", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "readiness", "gaps", "state" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "planningId": { "type": "string" }, "state": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/projects/planning/language": { "get": { "operationId": "projectPlanning.language.get", "summary": "Get Project Language", "description": "Return canonical project vocabulary and resolved ambiguity records from the project knowledge space.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "language": { "anyOf": [ { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "terms": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "ambiguities": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "examples": { "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "projectId", "knowledgeSpaceId", "terms", "ambiguities", "updatedAt" ], "additionalProperties": true }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "projectPlanning.language.upsert", "summary": "Upsert Project Language", "description": "Persist project vocabulary and ambiguity-resolution records without changing any live daemon session behavior.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "language": { "anyOf": [ { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "terms": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "ambiguities": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "examples": { "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "projectId", "knowledgeSpaceId", "terms", "ambiguities", "updatedAt" ], "additionalProperties": true }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "language": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "language" ], "additionalProperties": true } } } } } }, "/api/projects/planning/state": { "get": { "operationId": "projectPlanning.state.get", "summary": "Get Project Planning State", "description": "Return the current project-scoped planning state artifact. The TUI owns the active conversation loop.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "goal": { "type": "string" }, "scope": { "type": "string" }, "knownContext": { "type": "array", "items": { "type": "string" } }, "openQuestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "whyItMatters": { "type": "string" }, "recommendedAnswer": { "type": "string" }, "consequence": { "type": "string" }, "status": { "type": "string" }, "answer": { "type": "string" }, "answeredAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "prompt" ], "additionalProperties": true } }, "answeredQuestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "whyItMatters": { "type": "string" }, "recommendedAnswer": { "type": "string" }, "consequence": { "type": "string" }, "status": { "type": "string" }, "answer": { "type": "string" }, "answeredAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "prompt" ], "additionalProperties": true } }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "context": { "type": "string" }, "decision": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } }, "reasoning": { "type": "string" }, "consequences": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "decision" ], "additionalProperties": true } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "constraints": { "type": "array", "items": { "type": "string" } }, "risks": { "type": "array", "items": { "type": "string" } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "why": { "type": "string" }, "status": { "type": "string" }, "dependencies": { "type": "array", "items": { "type": "string" } }, "likelyFiles": { "type": "array", "items": { "type": "string" } }, "verification": { "type": "array", "items": { "type": "string" } }, "canRunConcurrently": { "type": "boolean" }, "needsReview": { "type": "boolean" }, "blockedOnUserInput": { "type": "boolean" }, "recommendedAgent": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title" ], "additionalProperties": true } }, "dependencies": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "verificationGates": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "agentAssignments": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "readiness": { "type": "string" }, "executionApproved": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "projectId", "knowledgeSpaceId", "goal", "knownContext", "openQuestions", "answeredQuestions", "decisions", "assumptions", "constraints", "risks", "tasks", "dependencies", "verificationGates", "agentAssignments", "readiness", "executionApproved", "createdAt", "updatedAt" ], "additionalProperties": true }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "planningId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "projectPlanning.state.upsert", "summary": "Upsert Project Planning State", "description": "Persist project-scoped planning state from the TUI interview loop and evaluate readiness.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "state": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "goal": { "type": "string" }, "scope": { "type": "string" }, "knownContext": { "type": "array", "items": { "type": "string" } }, "openQuestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "whyItMatters": { "type": "string" }, "recommendedAnswer": { "type": "string" }, "consequence": { "type": "string" }, "status": { "type": "string" }, "answer": { "type": "string" }, "answeredAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "prompt" ], "additionalProperties": true } }, "answeredQuestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "whyItMatters": { "type": "string" }, "recommendedAnswer": { "type": "string" }, "consequence": { "type": "string" }, "status": { "type": "string" }, "answer": { "type": "string" }, "answeredAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "prompt" ], "additionalProperties": true } }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "context": { "type": "string" }, "decision": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } }, "reasoning": { "type": "string" }, "consequences": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title", "decision" ], "additionalProperties": true } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "constraints": { "type": "array", "items": { "type": "string" } }, "risks": { "type": "array", "items": { "type": "string" } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "why": { "type": "string" }, "status": { "type": "string" }, "dependencies": { "type": "array", "items": { "type": "string" } }, "likelyFiles": { "type": "array", "items": { "type": "string" } }, "verification": { "type": "array", "items": { "type": "string" } }, "canRunConcurrently": { "type": "boolean" }, "needsReview": { "type": "boolean" }, "blockedOnUserInput": { "type": "boolean" }, "recommendedAgent": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "title" ], "additionalProperties": true } }, "dependencies": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "verificationGates": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "agentAssignments": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, {} ] } }, "readiness": { "type": "string" }, "executionApproved": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "projectId", "knowledgeSpaceId", "goal", "knownContext", "openQuestions", "answeredQuestions", "decisions", "assumptions", "constraints", "risks", "tasks", "dependencies", "verificationGates", "agentAssignments", "readiness", "executionApproved", "createdAt", "updatedAt" ], "additionalProperties": true }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "connectorId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "bookmark", "bookmark-list", "history", "document", "repo", "dataset", "image", "manual", "other" ] }, "title": { "type": "string" }, "sourceUri": { "type": "string" }, "canonicalUri": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "status": { "type": "string" }, "artifactId": { "type": "string" }, "contentHash": { "type": "string" }, "lastCrawledAt": { "type": "number" }, "crawlError": { "type": "string" }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "connectorId", "sourceType", "tags", "status", "metadata", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "state": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "state" ], "additionalProperties": true } } } } } }, "/api/projects/planning/status": { "get": { "operationId": "projectPlanning.status", "summary": "Project Planning Status", "description": "Return passive, project-scoped planning artifact counts and SDK capabilities without starting a planning loop.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "passiveOnly": { "type": "boolean" }, "counts": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "passiveOnly", "counts", "capabilities" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/projects/planning/work-plan/clear-completed": { "post": { "operationId": "projectPlanning.workPlan.clearCompleted", "summary": "Clear Completed Project Work Plan Tasks", "description": "Remove completed project work-plan tasks. Defaults to clearing status done only.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "task": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "previousTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "deletedTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "clearedTaskIds": { "type": "array", "items": { "type": "string" } }, "snapshot": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "blocked": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "blocked", "done", "failed", "cancelled" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "tasks", "counts", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "snapshot" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "statuses": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } } } }, "/api/projects/planning/work-plan": { "get": { "operationId": "projectPlanning.workPlan.snapshot", "summary": "Project Work Plan Snapshot", "description": "Return the durable project-scoped work-plan snapshot, including tasks and status counts.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "blocked": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "blocked", "done", "failed", "cancelled" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "tasks", "counts", "updatedAt" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workPlanId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "parentTaskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/projects/planning/work-plan/tasks": { "post": { "operationId": "projectPlanning.workPlan.task.create", "summary": "Create Project Work Plan Task", "description": "Create a durable project-scoped work-plan task for TUI, WebUI, APK, daemon planning, or WRFC correlation.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "task": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "previousTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "deletedTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "clearedTaskIds": { "type": "array", "items": { "type": "string" } }, "snapshot": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "blocked": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "blocked", "done", "failed", "cancelled" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "tasks", "counts", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "snapshot" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "task": { "type": "object", "properties": { "taskId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "title" ], "additionalProperties": true } }, "required": [ "task" ], "additionalProperties": true } } } } }, "get": { "operationId": "projectPlanning.workPlan.tasks.list", "summary": "List Project Work Plan Tasks", "description": "List durable project-scoped work-plan tasks with optional status, owner, parent, or WRFC-chain filters.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "blocked": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "blocked", "done", "failed", "cancelled" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "tasks", "counts", "updatedAt" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workPlanId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "parentTaskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/projects/planning/work-plan/tasks/{taskId}": { "delete": { "operationId": "projectPlanning.workPlan.task.delete", "summary": "Delete Project Work Plan Task", "description": "Delete a durable project-scoped work-plan task.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "task": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "previousTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "deletedTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "clearedTaskIds": { "type": "array", "items": { "type": "string" } }, "snapshot": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "blocked": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "blocked", "done", "failed", "cancelled" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "tasks", "counts", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "snapshot" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workPlanId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "get": { "operationId": "projectPlanning.workPlan.task.get", "summary": "Get Project Work Plan Task", "description": "Fetch one durable project-scoped work-plan task by id.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "task": { "anyOf": [ { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, { "type": "null" } ] }, "snapshot": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "blocked": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "blocked", "done", "failed", "cancelled" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "tasks", "counts", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "task", "snapshot" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:knowledge" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "knowledgeSpaceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workPlanId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "patch": { "operationId": "projectPlanning.workPlan.task.update", "summary": "Update Project Work Plan Task", "description": "Patch a durable project-scoped work-plan task.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "task": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "previousTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "deletedTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "clearedTaskIds": { "type": "array", "items": { "type": "string" } }, "snapshot": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "blocked": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "blocked", "done", "failed", "cancelled" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "tasks", "counts", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "snapshot" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "taskId": { "type": "string" }, "patch": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "patch" ], "additionalProperties": true } } } } } }, "/api/projects/planning/work-plan/tasks/{taskId}/status": { "post": { "operationId": "projectPlanning.workPlan.task.status", "summary": "Set Project Work Plan Task Status", "description": "Validate and apply a project work-plan task status transition.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "task": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "previousTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "deletedTask": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true }, "clearedTaskIds": { "type": "array", "items": { "type": "string" } }, "snapshot": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "blocked": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "blocked", "done", "failed", "cancelled" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "tasks", "counts", "updatedAt" ], "additionalProperties": true } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "snapshot" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "taskId": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" } }, "required": [ "taskId", "status" ], "additionalProperties": true } } } } } }, "/api/projects/planning/work-plan/tasks/reorder": { "post": { "operationId": "projectPlanning.workPlan.tasks.reorder", "summary": "Reorder Project Work Plan Tasks", "description": "Replace task ordering for the current project work plan.", "tags": [ "knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "owner": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "number" }, "order": { "type": "number" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "parentTaskId": { "type": "string" }, "chainId": { "type": "string" }, "phaseId": { "type": "string" }, "agentId": { "type": "string" }, "turnId": { "type": "string" }, "decisionId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "linkedArtifactIds": { "type": "array", "items": { "type": "string" } }, "linkedSourceIds": { "type": "array", "items": { "type": "string" } }, "linkedNodeIds": { "type": "array", "items": { "type": "string" } }, "originSurface": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "taskId", "projectId", "knowledgeSpaceId", "title", "status", "order", "tags", "linkedArtifactIds", "linkedSourceIds", "linkedNodeIds", "createdAt", "updatedAt" ], "additionalProperties": true } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "blocked": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "blocked", "done", "failed", "cancelled" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "ok", "projectId", "knowledgeSpaceId", "workPlanId", "tasks", "counts", "updatedAt" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "knowledgeSpaceId": { "type": "string" }, "workPlanId": { "type": "string" }, "orderedTaskIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "orderedTaskIds" ], "additionalProperties": true } } } } } }, "/api/mcp/config": { "get": { "operationId": "mcp.config.get", "summary": "MCP Effective Config", "description": "Return effective MCP config from global, external, and project sources. Environment values are redacted to envKeys.", "tags": [ "mcp" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "envKeys": { "type": "array", "items": { "type": "string" } }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trustMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "allowedHosts": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "required": [ "name", "command", "args", "envKeys", "role", "trustMode", "allowedPaths", "allowedHosts", "source" ], "additionalProperties": false } } }, "required": [ "locations", "servers" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:mcp" ] } }, "/api/mcp/reload": { "post": { "operationId": "mcp.config.reload", "summary": "Reload MCP Config", "description": "Reload effective MCP config and reconnect added, removed, or changed servers without daemon restart.", "tags": [ "mcp" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "reload": { "type": "object", "properties": { "added": { "type": "number" }, "changed": { "type": "number" }, "removed": { "type": "number" }, "unchanged": { "type": "number" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "action": { "type": "string", "enum": [ "added", "changed", "removed", "unchanged" ] }, "connected": { "type": "boolean" } }, "required": [ "name", "action", "connected" ], "additionalProperties": false } } }, "required": [ "added", "changed", "removed", "unchanged", "servers" ], "additionalProperties": false }, "config": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "envKeys": { "type": "array", "items": { "type": "string" } }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trustMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "allowedHosts": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "required": [ "name", "command", "args", "envKeys", "role", "trustMode", "allowedPaths", "allowedHosts", "source" ], "additionalProperties": false } } }, "required": [ "locations", "servers" ], "additionalProperties": false } }, "required": [ "reload", "config" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:mcp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/mcp/servers": { "get": { "operationId": "mcp.servers.list", "summary": "MCP Servers List", "description": "Return configured MCP servers, runtime security posture, and sandbox bindings.", "tags": [ "mcp" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "connected": { "type": "boolean" } }, "required": [ "name", "connected" ], "additionalProperties": false } }, "security": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "sandboxBindings": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "servers", "security", "sandboxBindings" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:mcp" ] } }, "/api/mcp/config/servers/{serverName}": { "delete": { "operationId": "mcp.servers.remove", "summary": "Remove MCP Server", "description": "Remove a project/global MCP server config and disconnect it without daemon restart.", "tags": [ "mcp" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "project", "global" ] }, "path": { "type": "string" }, "removed": { "type": "boolean" }, "reload": { "type": "object", "properties": { "added": { "type": "number" }, "changed": { "type": "number" }, "removed": { "type": "number" }, "unchanged": { "type": "number" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "action": { "type": "string", "enum": [ "added", "changed", "removed", "unchanged" ] }, "connected": { "type": "boolean" } }, "required": [ "name", "action", "connected" ], "additionalProperties": false } } }, "required": [ "added", "changed", "removed", "unchanged", "servers" ], "additionalProperties": false }, "config": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "envKeys": { "type": "array", "items": { "type": "string" } }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trustMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "allowedHosts": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "required": [ "name", "command", "args", "envKeys", "role", "trustMode", "allowedPaths", "allowedHosts", "source" ], "additionalProperties": false } } }, "required": [ "locations", "servers" ], "additionalProperties": false } }, "required": [ "scope", "path", "reload", "config" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:mcp" ], "parameters": [ { "name": "serverName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "project", "global" ] } } ] } }, "/api/mcp/servers/reveal": { "get": { "operationId": "mcp.servers.reveal", "summary": "MCP Servers Reveal", "description": "Return effective MCP config with environment VALUES included, not just envKeys. Admin only, the redacted mcp.config.get view is what every other caller should use.", "tags": [ "mcp" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "envKeys": { "type": "array", "items": { "type": "string" } }, "env": { "type": "object", "properties": {}, "additionalProperties": true }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trustMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "allowedHosts": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "required": [ "name", "command", "args", "envKeys", "env", "role", "trustMode", "allowedPaths", "allowedHosts", "source" ], "additionalProperties": false } } }, "required": [ "locations", "servers" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:mcp" ] } }, "/api/mcp/config/servers": { "post": { "operationId": "mcp.servers.upsert", "summary": "Upsert MCP Server", "description": "Persist a project/global MCP server config and reconnect the changed runtime server without daemon restart.", "tags": [ "mcp" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "project", "global" ] }, "path": { "type": "string" }, "removed": { "type": "boolean" }, "reload": { "type": "object", "properties": { "added": { "type": "number" }, "changed": { "type": "number" }, "removed": { "type": "number" }, "unchanged": { "type": "number" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "action": { "type": "string", "enum": [ "added", "changed", "removed", "unchanged" ] }, "connected": { "type": "boolean" } }, "required": [ "name", "action", "connected" ], "additionalProperties": false } } }, "required": [ "added", "changed", "removed", "unchanged", "servers" ], "additionalProperties": false }, "config": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "envKeys": { "type": "array", "items": { "type": "string" } }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trustMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "allowedHosts": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } }, "required": [ "scope", "kind", "path", "writable" ], "additionalProperties": false } }, "required": [ "name", "command", "args", "envKeys", "role", "trustMode", "allowedPaths", "allowedHosts", "source" ], "additionalProperties": false } } }, "required": [ "locations", "servers" ], "additionalProperties": false } }, "required": [ "scope", "path", "reload", "config" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:mcp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "project", "global" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "env": { "type": "object", "properties": {}, "additionalProperties": true }, "envKeys": { "type": "array", "items": { "type": "string" } }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trustMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "allowedHosts": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "command" ], "additionalProperties": false } }, "required": [ "server" ], "additionalProperties": true } } } } } }, "/api/mcp/tools": { "get": { "operationId": "mcp.tools.list", "summary": "MCP Tools List", "description": "Return currently connected MCP tools.", "tags": [ "mcp" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "qualifiedName": { "type": "string" }, "serverName": { "type": "string" }, "toolName": { "type": "string" }, "description": { "type": "string" } }, "required": [ "qualifiedName", "serverName", "toolName", "description" ], "additionalProperties": false } } }, "required": [ "tools" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:mcp" ] } }, "/api/media/analyze": { "post": { "operationId": "media.analyze", "summary": "Analyze Media Artifact", "description": "Analyze an artifact through a registered media provider.", "tags": [ "media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "description": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "providerId", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:media" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "mimeType": { "type": "string" }, "dataBase64": { "type": "string" }, "uri": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "mimeType", "metadata" ], "additionalProperties": false }, "artifactId": { "type": "string" }, "prompt": { "type": "string" }, "modelId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true, "anyOf": [ { "type": "object", "properties": { "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "mimeType": { "type": "string" }, "dataBase64": { "type": "string" }, "uri": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "mimeType", "metadata" ], "additionalProperties": false } }, "required": [ "artifact" ], "additionalProperties": true }, { "type": "object", "properties": { "artifactId": { "type": "string" } }, "required": [ "artifactId" ], "additionalProperties": true } ] } } } } } }, "/api/media/generate": { "post": { "operationId": "media.generate", "summary": "Generate Media Artifact", "description": "Generate a media artifact through a registered media provider.", "tags": [ "media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "mimeType": { "type": "string" }, "dataBase64": { "type": "string" }, "uri": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "acquisitionMode": { "type": "string", "enum": [ "inline-data", "local-path", "remote-fetch", "unknown" ] }, "fetchMode": { "type": "string", "enum": [ "not-applicable", "public-only", "allow-private-hosts", "unknown" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "mimeType", "metadata" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "providerId", "artifacts", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:media" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "prompt": { "type": "string" }, "outputMimeType": { "type": "string" }, "modelId": { "type": "string" }, "options": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "prompt" ], "additionalProperties": true } } } } } }, "/api/media/providers": { "get": { "operationId": "media.providers.list", "summary": "List Media Providers", "description": "Return registered media provider capabilities.", "tags": [ "media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "capabilities" ], "additionalProperties": false } } }, "required": [ "providers" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:media" ] } }, "/api/media/transform": { "post": { "operationId": "media.transform", "summary": "Transform Media Artifact", "description": "Transform an artifact through a registered media provider.", "tags": [ "media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "mimeType": { "type": "string" }, "dataBase64": { "type": "string" }, "uri": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "acquisitionMode": { "type": "string", "enum": [ "inline-data", "local-path", "remote-fetch", "unknown" ] }, "fetchMode": { "type": "string", "enum": [ "not-applicable", "public-only", "allow-private-hosts", "unknown" ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "mimeType", "metadata" ], "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "providerId", "artifact", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:media" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "mimeType": { "type": "string" }, "dataBase64": { "type": "string" }, "uri": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "mimeType", "metadata" ], "additionalProperties": false }, "operation": { "type": "string" }, "outputMimeType": { "type": "string" }, "options": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "artifact", "operation" ], "additionalProperties": true } } } } } }, "/api/multimodal/analyze": { "post": { "operationId": "multimodal.analyze", "summary": "Run Multimodal Analysis", "description": "Analyze an image, audio file, video artifact, or document through the unified multimodal service.", "tags": [ "media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "analysis": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true }, "providerIds": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "text": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "entities": { "type": "array", "items": { "type": "string" } }, "segments": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "confidence": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind", "metadata" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "artifact", "providerIds", "labels", "entities", "segments", "metadata" ], "additionalProperties": false }, "packet": { "type": "object", "properties": { "detail": { "type": "string" }, "budgetLimit": { "type": "number" }, "estimatedTokens": { "type": "number" }, "rendered": { "type": "string" }, "highlights": { "type": "array", "items": { "type": "string" } } }, "required": [ "detail", "budgetLimit", "estimatedTokens", "rendered", "highlights" ], "additionalProperties": false }, "writeback": { "type": "object", "properties": { "analysisArtifact": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true }, "knowledgeSourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "analysisArtifact", "metadata" ], "additionalProperties": false } }, "required": [ "analysis" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:media" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "artifactId": { "type": "string" }, "artifact": { "type": "object", "properties": { "artifactId": { "type": "string" }, "mimeType": { "type": "string" }, "dataBase64": { "type": "string" }, "uri": { "type": "string" }, "allowPrivateHosts": { "type": "boolean" }, "filename": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": false }, "prompt": { "type": "string" }, "imageProviderId": { "type": "string" }, "audioProviderId": { "type": "string" }, "modelId": { "type": "string" }, "language": { "type": "string" }, "detail": { "type": "string", "enum": [ "compact", "standard", "detailed" ] }, "allowPrivateHosts": { "type": "boolean" }, "includePacket": { "type": "boolean" }, "writeback": { "type": "object", "properties": { "sessionId": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": false }, "sessionId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/multimodal/packet": { "post": { "operationId": "multimodal.packet", "summary": "Build Multimodal Packet", "description": "Build a token-efficient packet from an existing multimodal analysis result.", "tags": [ "media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "packet": { "type": "object", "properties": { "detail": { "type": "string" }, "budgetLimit": { "type": "number" }, "estimatedTokens": { "type": "number" }, "rendered": { "type": "string" }, "highlights": { "type": "array", "items": { "type": "string" } } }, "required": [ "detail", "budgetLimit", "estimatedTokens", "rendered", "highlights" ], "additionalProperties": false } }, "required": [ "packet" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:media" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "analysis": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true }, "providerIds": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "text": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "entities": { "type": "array", "items": { "type": "string" } }, "segments": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "confidence": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind", "metadata" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "artifact", "providerIds", "labels", "entities", "segments", "metadata" ], "additionalProperties": false }, "detail": { "type": "string", "enum": [ "compact", "standard", "detailed" ] }, "budgetLimit": { "type": "number" } }, "required": [ "analysis" ], "additionalProperties": true } } } } } }, "/api/multimodal/providers": { "get": { "operationId": "multimodal.providers.list", "summary": "List Multimodal Providers", "description": "Return the normalized multimodal provider catalog spanning media understanding, speech-to-text, and extractors.", "tags": [ "media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "transport": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "configured": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "transport", "capabilities", "configured", "metadata" ], "additionalProperties": false } } }, "required": [ "providers" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:media" ] } }, "/api/multimodal": { "get": { "operationId": "multimodal.status", "summary": "Multimodal Status", "description": "Return the unified multimodal runtime status across image, audio, video, and document analysis.", "tags": [ "media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "providerCount": { "type": "number" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "transport": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "configured": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "transport", "capabilities", "configured", "metadata" ], "additionalProperties": false } }, "note": { "type": "string" } }, "required": [ "enabled", "providerCount", "providers", "note" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:media" ] } }, "/api/multimodal/writeback": { "post": { "operationId": "multimodal.writeback", "summary": "Write Back Multimodal Analysis", "description": "Persist a multimodal analysis result as an artifact and ingest it into the structured knowledge store.", "tags": [ "media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "writeback": { "type": "object", "properties": { "analysisArtifact": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true }, "knowledgeSourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "analysisArtifact", "metadata" ], "additionalProperties": false } }, "required": [ "writeback" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:media", "write:knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "analysis": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "artifact": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "mimeType": { "type": "string" }, "filename": { "type": "string" }, "sizeBytes": { "type": "number" }, "sha256": { "type": "string" }, "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "sourceUri": { "type": "string" }, "acquisitionMode": { "type": "string" }, "fetchMode": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "mimeType", "sizeBytes", "sha256", "createdAt", "metadata" ], "additionalProperties": true }, "providerIds": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "text": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "entities": { "type": "array", "items": { "type": "string" } }, "segments": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "confidence": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind", "metadata" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "artifact", "providerIds", "labels", "entities", "segments", "metadata" ], "additionalProperties": false }, "sessionId": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "analysis" ], "additionalProperties": true } } } } } }, "/api/memory/consolidation/receipts": { "get": { "operationId": "memory.consolidation.receipts", "summary": "Memory Consolidation Receipts", "description": "Return the retained memory-consolidation run receipts (what each idle/scheduled pass scanned, merged, archived, decayed) and the pending judgment PROPOSALS they carry (contradictions, cross-scope duplicates), the records a proposal references are already marked into the review queue, and a human resolves them through the confirmation-gated review route. A runtime without the consolidation scheduler answers an honest 501.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipts": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string" }, "ranAt": { "type": "string" }, "trigger": { "type": "string" }, "idle": { "type": "boolean" }, "scanned": { "type": "number" }, "merged": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "archived": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "decayed": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "proposed": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "contradiction", "cross-scope-duplicate", "stale-delete" ] }, "ids": { "type": "array", "items": { "type": "string" } }, "route": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "kind", "ids", "route", "reason" ], "additionalProperties": false } }, "usageSignalAvailable": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "runId", "ranAt", "trigger", "idle", "scanned", "merged", "archived", "decayed", "proposed", "usageSignalAvailable", "note" ], "additionalProperties": false } }, "pendingProposals": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "contradiction", "cross-scope-duplicate", "stale-delete" ] }, "ids": { "type": "array", "items": { "type": "string" } }, "route": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "kind", "ids", "route", "reason" ], "additionalProperties": false } } }, "required": [ "receipts", "pendingProposals" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ] } }, "/api/memory/doctor": { "get": { "operationId": "memory.doctor", "summary": "Memory Doctor", "description": "Return sqlite-vec and memory embedding-provider diagnostics.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "vector": { "type": "object", "properties": { "backend": { "type": "string", "enum": [ "sqlite-vec" ] }, "enabled": { "type": "boolean" }, "available": { "type": "boolean" }, "path": { "type": "string" }, "dimensions": { "type": "number" }, "indexedRecords": { "type": "number" }, "embeddingProviderId": { "type": "string" }, "embeddingProviderLabel": { "type": "string" }, "error": { "type": "string" }, "platformLimitReason": { "type": "string" } }, "required": [ "backend", "enabled", "available", "path", "dimensions", "indexedRecords", "embeddingProviderId", "embeddingProviderLabel" ], "additionalProperties": true }, "embeddings": { "type": "object", "properties": { "activeProviderId": { "type": "string" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "healthy", "degraded", "disabled", "unconfigured" ] }, "dimensions": { "type": "number" }, "configured": { "type": "boolean" }, "deterministic": { "type": "boolean" }, "detail": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "state", "dimensions", "configured", "metadata" ], "additionalProperties": true } }, "asyncProviders": { "type": "array", "items": { "type": "string" } }, "syncProviders": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "activeProviderId", "providers", "asyncProviders", "syncProviders", "warnings" ], "additionalProperties": false }, "checkedAt": { "type": "number" } }, "required": [ "vector", "embeddings", "checkedAt" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ] } }, "/api/memory/embeddings/default": { "post": { "operationId": "memory.embeddings.default.set", "summary": "Set Default Memory Embedding Provider", "description": "Set the active default memory embedding provider.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "vector": { "type": "object", "properties": { "backend": { "type": "string", "enum": [ "sqlite-vec" ] }, "enabled": { "type": "boolean" }, "available": { "type": "boolean" }, "path": { "type": "string" }, "dimensions": { "type": "number" }, "indexedRecords": { "type": "number" }, "embeddingProviderId": { "type": "string" }, "embeddingProviderLabel": { "type": "string" }, "error": { "type": "string" }, "platformLimitReason": { "type": "string" } }, "required": [ "backend", "enabled", "available", "path", "dimensions", "indexedRecords", "embeddingProviderId", "embeddingProviderLabel" ], "additionalProperties": true }, "embeddings": { "type": "object", "properties": { "activeProviderId": { "type": "string" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "healthy", "degraded", "disabled", "unconfigured" ] }, "dimensions": { "type": "number" }, "configured": { "type": "boolean" }, "deterministic": { "type": "boolean" }, "detail": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "state", "dimensions", "configured", "metadata" ], "additionalProperties": true } }, "asyncProviders": { "type": "array", "items": { "type": "string" } }, "syncProviders": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "activeProviderId", "providers", "asyncProviders", "syncProviders", "warnings" ], "additionalProperties": false }, "checkedAt": { "type": "number" } }, "required": [ "vector", "embeddings", "checkedAt" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" } }, "required": [ "providerId" ], "additionalProperties": true } } } } } }, "/api/memory/projections/{id}": { "get": { "operationId": "memory.projections.get", "summary": "Get Memory Projection", "description": "Return one standing record's projection by id: its metadata entry plus the exact markdown the file projection would write (front-matter + content, with the live temporal status labelled). Returns 404 when no standing (project/team) record has that id, a session-scope or unknown id is an honest miss, never an empty projection.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "projection": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "number" }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "validFrom": { "type": "number" }, "validUntil": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "pending", "expired" ] } }, "required": [ "id", "filename", "scope", "cls", "summary", "tags", "confidence", "reviewState", "status" ], "additionalProperties": false }, "markdown": { "type": "string" } }, "required": [ "projection", "markdown" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/memory/projections": { "get": { "operationId": "memory.projections.list", "summary": "List Memory Projections", "description": "Return the live projection of standing (project/team-scope) memory records, one metadata entry per record (id, filename, scope, class, summary, tags, confidence, review state, temporal validity + status), oldest first. This is the read view over the same standing memory the file projection writes as markdown; session-scope records are excluded (they are not standing memory). Computed live from the store, never read from disk, so it always matches the current records. An expired record is present with status:\"expired\" rather than silently dropped.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "projections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "number" }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "validFrom": { "type": "number" }, "validUntil": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "pending", "expired" ] } }, "required": [ "id", "filename", "scope", "cls", "summary", "tags", "confidence", "reviewState", "status" ], "additionalProperties": false } } }, "required": [ "projections" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ] } }, "/api/memory/records": { "post": { "operationId": "memory.records.add", "summary": "Add Memory Record", "description": "Add a memory record to the daemon-owned canonical store. The daemon is the single writer for its store; a client surface routes its writes here instead of opening the store file, so two processes never write the same sql.js file. New records default to confidence 60 (the recall floor) and reviewState fresh unless the review block overrides them.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedAt": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "scope", "cls", "summary", "tags", "provenance", "reviewState", "confidence", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "record" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "review": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" } }, "additionalProperties": false } }, "required": [ "cls", "summary" ], "additionalProperties": true } } } } } }, "/api/memory/records/{id}": { "delete": { "operationId": "memory.records.delete", "summary": "Delete Memory Record", "description": "Permanently delete a memory record and its links from the canonical store. Delete means delete: the record is removed from the store and the semantic index, not merely flagged. Returns { deleted: false } when no record with that id existed, an honest boolean, never a 200 that pretends a phantom row was removed.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "get": { "operationId": "memory.records.get", "summary": "Get Memory Record", "description": "Return a single memory record by id from the canonical store, or 404 when no record with that id exists.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedAt": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "scope", "cls", "summary", "tags", "provenance", "reviewState", "confidence", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "record" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/memory/records/export": { "post": { "operationId": "memory.records.export", "summary": "Export Memory Bundle", "description": "Export a no-loss bundle (records + links) for the given filter from the canonical store. The bundle round-trips through import id-keyed, so it is the wire form of the cross-surface fold/reconcile seam. Read-only.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "schemaVersion": { "type": "string", "enum": [ "v1" ] }, "exportedAt": { "type": "number" }, "scope": { "type": "string", "enum": [ "session", "project", "team", "all" ] }, "recordCount": { "type": "number" }, "linkCount": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedAt": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "scope", "cls", "summary", "tags", "provenance", "reviewState", "confidence", "createdAt", "updatedAt" ], "additionalProperties": true } }, "links": { "type": "array", "items": { "type": "object", "properties": { "fromId": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "fromId", "toId", "relation", "createdAt" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "exportedAt", "scope", "recordCount", "linkCount", "records", "links" ], "additionalProperties": false } }, "required": [ "bundle" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "query": { "type": "string" }, "semantic": { "type": "boolean" }, "since": { "type": "number" }, "reviewState": { "type": "array", "items": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] } }, "minConfidence": { "type": "number" }, "provenanceKinds": { "type": "array", "items": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] } }, "staleOnly": { "type": "boolean" }, "limit": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/memory/records/import": { "post": { "operationId": "memory.records.import", "summary": "Import Memory Bundle", "description": "Import a bundle into the canonical store as an id-keyed union: an id already present is left untouched (counted skipped), a new id is added; a link is added only when both its endpoints exist. Never overwrites, never deletes, idempotent on re-run. The daemon is the single writer, so a client imports here instead of writing the store file.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "importedRecords": { "type": "number" }, "skippedRecords": { "type": "number" }, "importedLinks": { "type": "number" } }, "required": [ "importedRecords", "skippedRecords", "importedLinks" ], "additionalProperties": false } }, "required": [ "result" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "schemaVersion": { "type": "string", "enum": [ "v1" ] }, "exportedAt": { "type": "number" }, "scope": { "type": "string", "enum": [ "session", "project", "team", "all" ] }, "recordCount": { "type": "number" }, "linkCount": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedAt": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "scope", "cls", "summary", "tags", "provenance", "reviewState", "confidence", "createdAt", "updatedAt" ], "additionalProperties": true } }, "links": { "type": "array", "items": { "type": "object", "properties": { "fromId": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "fromId", "toId", "relation", "createdAt" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "exportedAt", "scope", "recordCount", "linkCount", "records", "links" ], "additionalProperties": false } }, "required": [ "bundle" ], "additionalProperties": true } } } } } }, "/api/memory/records/{id}/links": { "post": { "operationId": "memory.records.links.add", "summary": "Link Memory Records", "description": "Create a directed relation (e.g. \"supersedes\", \"caused\") from the path record to a target record. Returns 404 when either endpoint does not exist, never a 200 that pretends a link was made between records that do not both exist.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "object", "properties": { "fromId": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "fromId", "toId", "relation", "createdAt" ], "additionalProperties": false } }, "required": [ "link" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" } }, "required": [ "id", "toId", "relation" ], "additionalProperties": true } } } } }, "get": { "operationId": "memory.records.links.list", "summary": "List Memory Record Links", "description": "Return every link where the record is the source or the target. Returns 404 when no record with that id exists, an honest not-found, distinct from a record that exists but has no links (an empty array).", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "fromId": { "type": "string" }, "toId": { "type": "string" }, "relation": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "fromId", "toId", "relation", "createdAt" ], "additionalProperties": false } } }, "required": [ "links" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/memory/records/list": { "post": { "operationId": "memory.records.list", "summary": "List Memory Records", "description": "Bulk read from the canonical store: a literal (non-semantic) search returning the matching records as a plain array. An empty filter returns every record (getAll). This is the read a client surface uses instead of opening the store file for its browse/list and knowledge-injection paths.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedAt": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "scope", "cls", "summary", "tags", "provenance", "reviewState", "confidence", "createdAt", "updatedAt" ], "additionalProperties": true } } }, "required": [ "records" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "query": { "type": "string" }, "semantic": { "type": "boolean" }, "since": { "type": "number" }, "reviewState": { "type": "array", "items": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] } }, "minConfidence": { "type": "number" }, "provenanceKinds": { "type": "array", "items": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] } }, "staleOnly": { "type": "boolean" }, "limit": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/memory/records/search": { "post": { "operationId": "memory.records.search", "summary": "Search Memory Records", "description": "Search the canonical store, literal or semantic. When semantic is requested but the semantic index cannot be consulted, the search falls back to a literal scan and states the reason in indexUnavailableReason rather than returning a silent empty result that reads as \"nothing was ever stored\". With recall=true the cross-surface recall-honesty contract is applied: flagged (stale/contradicted) records are excluded outright and records below the 60% confidence floor are dropped, each exclusion counted honestly.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedAt": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "scope", "cls", "summary", "tags", "provenance", "reviewState", "confidence", "createdAt", "updatedAt" ], "additionalProperties": true } }, "mode": { "type": "string", "enum": [ "literal", "semantic" ] }, "requestedSemantic": { "type": "boolean" }, "indexUnavailableReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "caveat": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recallFiltered": { "type": "boolean" }, "excludedFlaggedCount": { "type": "number" }, "excludedBelowFloorCount": { "type": "number" }, "totalBeforeRecallFilter": { "type": "number" }, "recallFloor": { "type": "number" } }, "required": [ "records", "mode", "requestedSemantic", "indexUnavailableReason", "caveat", "recallFiltered", "excludedFlaggedCount", "excludedBelowFloorCount", "totalBeforeRecallFilter", "recallFloor" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "query": { "type": "string" }, "semantic": { "type": "boolean" }, "since": { "type": "number" }, "reviewState": { "type": "array", "items": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] } }, "minConfidence": { "type": "number" }, "provenanceKinds": { "type": "array", "items": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] } }, "staleOnly": { "type": "boolean" }, "limit": { "type": "number" }, "recall": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/memory/records/search-semantic": { "post": { "operationId": "memory.records.search-semantic", "summary": "Semantic Search Memory Records", "description": "Rank records by semantic similarity against the query, returning scored results (distance, similarity, score). When the query has no vector match the store falls back to a lexical ranking rather than a silent empty. distance is null for a fallback (non-vector) result. Read-only against the daemon's canonical index.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "record": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedAt": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "scope", "cls", "summary", "tags", "provenance", "reviewState", "confidence", "createdAt", "updatedAt" ], "additionalProperties": true }, "distance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "similarity": { "type": "number" }, "score": { "type": "number" } }, "required": [ "record", "similarity", "score" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "query": { "type": "string" }, "semantic": { "type": "boolean" }, "since": { "type": "number" }, "reviewState": { "type": "array", "items": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] } }, "minConfidence": { "type": "number" }, "provenanceKinds": { "type": "array", "items": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] } }, "staleOnly": { "type": "boolean" }, "limit": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/memory/records/{id}/update": { "post": { "operationId": "memory.records.update", "summary": "Update Memory Record", "description": "Edit a record's content fields (scope, summary, detail, tags) and its temporal validity window (validFrom, validUntil) in the canonical store. This is distinct from the review update: it changes the record itself, e.g. moving scope project→team promotes a record to the shared surface. For validFrom/validUntil a number sets the bound, null clears it, and an omitted field leaves it unchanged, so a proposal that changes only the window can be applied. Returns 404 when no record with that id exists.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedAt": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "scope", "cls", "summary", "tags", "provenance", "reviewState", "confidence", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "record" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "validFrom": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "validUntil": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": true } } } } } }, "/api/memory/records/{id}/review": { "post": { "operationId": "memory.records.update-review", "summary": "Update Memory Record Review", "description": "Update a record's review signal (reviewState, confidence, reviewer, staleReason) in the canonical store. Marking a record stale or contradicted flags it so the recall-honesty contract will never inject it into a prompt again regardless of confidence. Returns 404 when no record with that id exists.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "session", "project", "team" ] }, "cls": { "type": "string", "enum": [ "decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership" ] }, "summary": { "type": "string" }, "detail": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "session", "turn", "task", "event", "file" ] }, "ref": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "ref" ], "additionalProperties": false } }, "reviewState": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedAt": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "scope", "cls", "summary", "tags", "provenance", "reviewState", "confidence", "createdAt", "updatedAt" ], "additionalProperties": true } }, "required": [ "record" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "fresh", "reviewed", "stale", "contradicted" ] }, "confidence": { "type": "number" }, "reviewedBy": { "type": "string" }, "staleReason": { "type": "string" } }, "required": [ "id" ], "additionalProperties": true } } } } } }, "/api/memory/review-queue": { "get": { "operationId": "memory.review-queue", "summary": "Memory Review Queue", "description": "Return memory records prioritised for review. Accepts optional limit (?limit=N) and scope filter (?scope=session|project|team). A scope query parameter that is present but not one of the three valid values returns 400.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "records" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "session", "project", "team" ] } } ] } }, "/api/memory/vector/rebuild": { "post": { "operationId": "memory.vector.rebuild", "summary": "Rebuild Memory Vector Index", "description": "Rebuild the sqlite-vec vector index.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "vector": { "type": "object", "properties": { "backend": { "type": "string", "enum": [ "sqlite-vec" ] }, "enabled": { "type": "boolean" }, "available": { "type": "boolean" }, "path": { "type": "string" }, "dimensions": { "type": "number" }, "indexedRecords": { "type": "number" }, "embeddingProviderId": { "type": "string" }, "embeddingProviderLabel": { "type": "string" }, "error": { "type": "string" }, "platformLimitReason": { "type": "string" } }, "required": [ "backend", "enabled", "available", "path", "dimensions", "indexedRecords", "embeddingProviderId", "embeddingProviderLabel" ], "additionalProperties": true } }, "required": [ "vector" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/memory/vector": { "get": { "operationId": "memory.vector.stats", "summary": "Memory Vector Stats", "description": "Return the current sqlite-vec vector-store posture.", "tags": [ "memory" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "vector": { "type": "object", "properties": { "backend": { "type": "string", "enum": [ "sqlite-vec" ] }, "enabled": { "type": "boolean" }, "available": { "type": "boolean" }, "path": { "type": "string" }, "dimensions": { "type": "number" }, "indexedRecords": { "type": "number" }, "embeddingProviderId": { "type": "string" }, "embeddingProviderLabel": { "type": "string" }, "error": { "type": "string" }, "platformLimitReason": { "type": "string" } }, "required": [ "backend", "enabled", "available", "path", "dimensions", "indexedRecords", "embeddingProviderId", "embeddingProviderLabel" ], "additionalProperties": true } }, "required": [ "vector" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:memory" ] } }, "/api/occasions/acknowledge": { "post": { "operationId": "occasions.acknowledge", "summary": "Acknowledge An Occasion", "description": "Record that the owner has one occurrence in hand, so nothing is pushed at them about it again. This is not a yes and not a no: the open item STAYS OPEN and stays enumerable, so occasions.pending still lists it, under acknowledged[] rather than in the nudge, and asking what is coming up still answers with it. Only the push stops. The record expires with its occurrence, so next year asks fresh. source names how it was recorded: conversation when the owner said so in a reply, explicit when a surface offered the action, gift-flow when the owner is already answering gift questions about it.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reply": { "type": "string" } }, "required": [ "ok", "reason", "reply" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "occasionId": { "type": "string" }, "source": { "type": "string", "enum": [ "conversation", "explicit", "gift-flow" ] }, "occurrence": { "type": "string" } }, "required": [ "occasionId" ], "additionalProperties": false } } } } } }, "/api/occasions/answer": { "post": { "operationId": "occasions.answer", "summary": "Answer An Occasion Nudge", "description": "Record yes, no or later for one occurrence. A no goes silent for the rest of this cycle and expires with the date, so next year asks fresh carrying no memory of the refusal. A later is NOT a decline, it comes back roughly halfway to the date. A yes on a gift-giving occasion opens the short interview and returns its first question. All three RESOLVE the open item and remove it; to say only \"I have this in hand\" without ending the question, use occasions.acknowledge instead.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "interview": { "anyOf": [ { "type": "object", "properties": { "interviewId": { "type": "string" }, "occasionId": { "type": "string" }, "occurrence": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false } }, "nextStep": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "landedOn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "interviewId", "occasionId", "occurrence", "steps", "nextStep", "complete", "landedOn" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "ok", "reason", "interview" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "occasionId": { "type": "string" }, "answer": { "type": "string", "enum": [ "yes", "no", "later", "acknowledged" ] }, "occurrence": { "type": "string" } }, "required": [ "occasionId", "answer" ], "additionalProperties": false } } } } } }, "/api/occasions/confirm": { "post": { "operationId": "occasions.confirm", "summary": "Record A Confirmed Important Date", "description": "Write the confirmed occasion as one line in the owner profile, under Important dates, carrying its provenance. This is the ONE confirmation: nothing re-confirms at nudge time, because for an annual date a silent write means the mistake surfaces up to eleven months later. Refused without a kind rather than defaulting one. Goes through the owner-profile write gate, so authority, surface and a verbatim quote of what the owner said are all required.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occasionId": { "type": "string" }, "disclosure": { "type": "string" }, "droppedRecords": { "type": "number" } }, "required": [ "ok", "reason", "occasionId", "disclosure", "droppedRecords" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "date": { "type": "string" }, "kind": { "type": "string", "enum": [ "gift-giving", "remember-only", "neither" ] }, "person": { "type": "string" }, "recurrence": { "type": "string", "enum": [ "annual", "once" ] }, "leadDays": { "type": "number" }, "surface": { "type": "string" }, "said": { "type": "string" }, "authority": { "type": "string" } }, "required": [ "title", "date", "kind", "surface", "said", "authority" ], "additionalProperties": false } } } } } }, "/api/occasions/conflict/resolve": { "post": { "operationId": "occasions.conflict.resolve", "summary": "Close A Date Conflict", "description": "Stop re-raising a conflict the owner has dealt with. The conflict itself is never resolved automatically, two different dates for one thing means only the owner knows which was right, and silently taking the newer value is the behaviour this exists to prevent.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "occasionId": { "type": "string" }, "resolved": { "type": "boolean" } }, "required": [ "occasionId", "resolved" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "occasionId": { "type": "string" } }, "required": [ "occasionId" ], "additionalProperties": false } } } } } }, "/api/occasions/gifts": { "post": { "operationId": "occasions.gifts", "summary": "List Gift History", "description": "Return what the owner landed on for one occasion in previous years, newest first. Kept beyond the answers deliberately: the answers expire with their date so next year asks fresh, the history does not.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "occasionId": { "type": "string" }, "gifts": { "type": "array", "items": { "type": "object", "properties": { "occasionId": { "type": "string" }, "occurrence": { "type": "string" }, "recordedAt": { "type": "number" }, "landedOn": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "occasionId", "occurrence", "recordedAt", "landedOn" ], "additionalProperties": false } } }, "required": [ "occasionId", "gifts" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "occasionId": { "type": "string" } }, "required": [ "occasionId" ], "additionalProperties": false } } } } } }, "/api/occasions/interview/answer": { "post": { "operationId": "occasions.interview.answer", "summary": "Answer A Gift Interview Question", "description": "Record one answer and return the next question, if there is one. The interview guides the owner to their own idea and never recommends a gift, that judgement is the owner's, which is also why the outcome recorded is what the owner landed on rather than what was suggested.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "present": { "type": "boolean" }, "interview": { "anyOf": [ { "type": "object", "properties": { "interviewId": { "type": "string" }, "occasionId": { "type": "string" }, "occurrence": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false } }, "nextStep": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "landedOn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "interviewId", "occasionId", "occurrence", "steps", "nextStep", "complete", "landedOn" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "present", "interview" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interviewId": { "type": "string" }, "stepId": { "type": "string" }, "text": { "type": "string" } }, "required": [ "interviewId", "stepId", "text" ], "additionalProperties": false } } } } } }, "/api/occasions/interview": { "post": { "operationId": "occasions.interview.get", "summary": "Get Gift Interview", "description": "Return one gift interview and the question that has not been answered yet. A thread the owner walked away from resumes here rather than restarting: the next step is the one the owner did not get to. Over a channel the steps are asked one at a time; in the agent they can be one exchange.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "present": { "type": "boolean" }, "interview": { "anyOf": [ { "type": "object", "properties": { "interviewId": { "type": "string" }, "occasionId": { "type": "string" }, "occurrence": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false } }, "nextStep": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "landedOn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "interviewId", "occasionId", "occurrence", "steps", "nextStep", "complete", "landedOn" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "present", "interview" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interviewId": { "type": "string" } }, "required": [ "interviewId" ], "additionalProperties": false } } } } } }, "/api/occasions/interview/record": { "post": { "operationId": "occasions.interview.record", "summary": "Record What The Owner Landed On", "description": "Close the interview with what the owner settled on and write it to the gift history. Recording the outcome rather than merely that the owner said yes is the point: \"said yes in 2026\" cannot stop year three steering where year one did.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "present": { "type": "boolean" }, "interview": { "anyOf": [ { "type": "object", "properties": { "interviewId": { "type": "string" }, "occasionId": { "type": "string" }, "occurrence": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false } }, "nextStep": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "landedOn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "interviewId", "occasionId", "occurrence", "steps", "nextStep", "complete", "landedOn" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "present", "interview" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interviewId": { "type": "string" }, "landedOn": { "type": "string" } }, "required": [ "interviewId", "landedOn" ], "additionalProperties": false } } } } } }, "/api/occasions": { "get": { "operationId": "occasions.list", "summary": "List Important Dates", "description": "Return every occasion declared in the owner profile, with its next occurrence, how many days away it is, the lead it uses, whether it is inside its lead window, and what was answered for that occurrence. Also returns lines under the heading that could not be typed, each with the reason, and any occasion that has two different dates recorded. This carries the dates: it is the owner asking their own system what it holds, which is the explicit ask that unlocks a closed-tier read. A nudge never does.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "today": { "type": "string" }, "timezone": { "type": "string" }, "occasions": { "type": "array", "items": { "type": "object", "properties": { "occasion": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "date": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "recurring", "dated" ] }, "year": { "type": "number" }, "month": { "type": "number" }, "day": { "type": "number" } }, "required": [ "kind", "month", "day" ], "additionalProperties": false }, "recurrence": { "type": "string", "enum": [ "annual", "once" ] }, "kind": { "type": "string", "enum": [ "gift-giving", "remember-only", "neither" ] }, "person": { "type": "string" }, "selfDeclared": { "type": "boolean" }, "subject": { "type": "string", "enum": [ "owner", "other", "unattributed" ] }, "leadDays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "mirrored": { "type": "boolean" }, "extras": { "type": "array", "items": { "type": "string" } }, "lineIndex": { "type": "number" }, "text": { "type": "string" } }, "required": [ "id", "title", "date", "recurrence", "kind", "person", "selfDeclared", "subject", "leadDays", "mirrored", "extras", "lineIndex", "text" ], "additionalProperties": false }, "nextOccurrence": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysUntil": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "leadDays": { "type": "number" }, "inLeadWindow": { "type": "boolean" }, "answer": { "anyOf": [ { "type": "string", "enum": [ "yes", "no", "later", "acknowledged" ] }, { "type": "null" } ] }, "mirrored": { "type": "boolean" } }, "required": [ "occasion", "nextOccurrence", "daysUntil", "leadDays", "inLeadWindow", "answer", "mirrored" ], "additionalProperties": false } }, "unparsed": { "type": "array", "items": { "type": "object", "properties": { "lineIndex": { "type": "number" }, "text": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "lineIndex", "text", "reason" ], "additionalProperties": false } }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "occasionId": { "type": "string" }, "title": { "type": "string" }, "dates": { "type": "array", "items": { "type": "string" } }, "lineIndexes": { "type": "array", "items": { "type": "number" } } }, "required": [ "occasionId", "title", "dates", "lineIndexes" ], "additionalProperties": false } } }, "required": [ "today", "timezone", "occasions", "unparsed", "conflicts" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:occasions" ] } }, "/api/occasions/pending": { "get": { "operationId": "occasions.pending", "summary": "Pull Outstanding Occasions", "description": "Return everything unresolved, without delivering anything: the batched nudge, any date conflict still open, and any interview left mid-thread. This is how a surface that is not a push destination receives a nudge, it pulls at the start of a turn rather than being pushed at, and a stored date is the prior scheduling that permits raising something unprompted. A nudge a push has already landed on the agent is left out while the agent is a configured push destination, so the push and the pull cannot raise the same thing twice; an item no push has ever landed there is still returned, so a missing sender or a failed send loses nothing. The nudge names the occasion and the person and NEVER the date: proximity is a word, not a count of days.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "today": { "type": "string" }, "nudge": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "raisedAt": { "type": "number" }, "subjects": { "type": "array", "items": { "type": "object", "properties": { "occasionId": { "type": "string" }, "title": { "type": "string" }, "person": { "type": "string" }, "kind": { "type": "string", "enum": [ "gift-giving", "remember-only", "neither" ] }, "proximity": { "type": "string", "enum": [ "approaching", "soon", "imminent" ] }, "subject": { "type": "string", "enum": [ "owner", "other", "unattributed" ] }, "acknowledged": { "type": "boolean" } }, "required": [ "occasionId", "title", "person", "kind", "proximity", "subject", "acknowledged" ], "additionalProperties": false } }, "message": { "type": "string" }, "answerable": { "type": "boolean" } }, "required": [ "id", "raisedAt", "subjects", "message", "answerable" ], "additionalProperties": false }, { "type": "null" } ] }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "occasionId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "occasionId", "message" ], "additionalProperties": false } }, "acknowledged": { "type": "array", "items": { "type": "object", "properties": { "occasionId": { "type": "string" }, "title": { "type": "string" }, "person": { "type": "string" }, "kind": { "type": "string", "enum": [ "gift-giving", "remember-only", "neither" ] }, "proximity": { "type": "string", "enum": [ "approaching", "soon", "imminent" ] }, "subject": { "type": "string", "enum": [ "owner", "other", "unattributed" ] }, "acknowledged": { "type": "boolean" } }, "required": [ "occasionId", "title", "person", "kind", "proximity", "subject", "acknowledged" ], "additionalProperties": false } }, "interviews": { "type": "array", "items": { "type": "object", "properties": { "interviewId": { "type": "string" }, "occasionId": { "type": "string" }, "occurrence": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false } }, "nextStep": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "opensFrom": { "type": "string" } }, "required": [ "id", "prompt", "opensFrom" ], "additionalProperties": false }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "landedOn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "interviewId", "occasionId", "occurrence", "steps", "nextStep", "complete", "landedOn" ], "additionalProperties": false } } }, "required": [ "today", "nudge", "acknowledged", "conflicts", "interviews" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:occasions" ] } }, "/api/occasions/plans/confirm": { "post": { "operationId": "occasions.plans.confirm", "summary": "Record A Confirmed Plan", "description": "Write the confirmed plan as one line in the owner profile, under Plans, carrying its provenance. Same one-confirmation rule and the same owner-profile write gate as an occasion.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occasionId": { "type": "string" }, "disclosure": { "type": "string" }, "droppedRecords": { "type": "number" } }, "required": [ "ok", "reason", "occasionId", "disclosure", "droppedRecords" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "away": { "type": "boolean" }, "destination": { "type": "string" }, "surface": { "type": "string" }, "said": { "type": "string" }, "authority": { "type": "string" } }, "required": [ "title", "from", "to", "surface", "said", "authority" ], "additionalProperties": false } } } } } }, "/api/occasions/plans": { "get": { "operationId": "occasions.plans.list", "summary": "List Plans", "description": "Return every plan declared in the owner profile, a dated range with attributes, plus whichever one has the owner away today. Plans are ambient: they never prompt. They exist so the system knows not to suggest things into that window, and so a nudge that would land while the owner is abroad moves to the day before they leave.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "today": { "type": "string" }, "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "away": { "type": "boolean" }, "destination": { "type": "string" }, "extras": { "type": "array", "items": { "type": "string" } }, "lineIndex": { "type": "number" }, "text": { "type": "string" } }, "required": [ "id", "title", "from", "to", "away", "destination", "extras", "lineIndex", "text" ], "additionalProperties": false } }, "unparsed": { "type": "array", "items": { "type": "object", "properties": { "lineIndex": { "type": "number" }, "text": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "lineIndex", "text", "reason" ], "additionalProperties": false } }, "awayNow": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "away": { "type": "boolean" }, "destination": { "type": "string" }, "extras": { "type": "array", "items": { "type": "string" } }, "lineIndex": { "type": "number" }, "text": { "type": "string" } }, "required": [ "id", "title", "from", "to", "away", "destination", "extras", "lineIndex", "text" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "today", "plans", "unparsed", "awayNow" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:occasions" ] } }, "/api/occasions/plans/propose": { "post": { "operationId": "occasions.plans.propose", "summary": "Propose A Plan", "description": "Work out what would be written for a plan heard in conversation, and return the one-line confirmation. Writes nothing. Away is opt-in rather than assumed: \"the kitchen is being redone, 3rd to the 10th\" is a real dated range that is not the owner leaving the house.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line": { "type": "string" }, "confirmation": { "type": "string" }, "needsKind": { "type": "boolean" }, "conflictsWith": { "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "reason", "line", "confirmation", "needsKind", "conflictsWith" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "away": { "type": "boolean" }, "destination": { "type": "string" } }, "required": [ "title", "from", "to" ], "additionalProperties": false } } } } } }, "/api/occasions/propose": { "post": { "operationId": "occasions.propose", "summary": "Propose An Important Date", "description": "Work out what would be written for a date heard in conversation, and return the one-line confirmation to put to the owner. WRITES NOTHING. When no kind was given, needsKind is true and the confirmation asks for it in the same breath, the kind is the owner's choice and is never inferred, because no rule that reads a label tells a birthday from a death anniversary. Any date already recorded for the same name that disagrees comes back in conflictsWith.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line": { "type": "string" }, "confirmation": { "type": "string" }, "needsKind": { "type": "boolean" }, "conflictsWith": { "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "reason", "line", "confirmation", "needsKind", "conflictsWith" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "date": { "type": "string" }, "kind": { "type": "string", "enum": [ "gift-giving", "remember-only", "neither" ] }, "person": { "type": "string" }, "recurrence": { "type": "string", "enum": [ "annual", "once" ] }, "leadDays": { "type": "number" } }, "required": [ "title", "date" ], "additionalProperties": false } } } } } }, "/api/occasions/remove": { "post": { "operationId": "occasions.remove", "summary": "Remove An Important Date", "description": "Remove one occasion and every record the machine kept against it, answers, gift history, open items, interviews and calendar mirrors. Takes exactly one confirmation: not unquestioned, and not an argument. People divorce and people die. A confirmed:false call returns the sentence to put to the owner and removes nothing.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occasionId": { "type": "string" }, "disclosure": { "type": "string" }, "droppedRecords": { "type": "number" } }, "required": [ "ok", "reason", "occasionId", "disclosure", "droppedRecords" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "occasionId": { "type": "string" }, "confirmed": { "type": "boolean" }, "authority": { "type": "string" } }, "required": [ "occasionId", "confirmed", "authority" ], "additionalProperties": false } } } } } }, "/api/occasions/state": { "get": { "operationId": "occasions.state", "summary": "Occasions State Disclosure", "description": "What the machine-owned store is holding, counts of answers, gift records, open items, interviews and calendar mirrors, plus what the last housekeeping pass removed and why, and whether the file was found unreadable. Counts and reasons only: no answer, no gift and no date is returned, which is what makes this safe in a support bundle.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "acknowledgements": { "type": "number" }, "giftRecords": { "type": "number" }, "openItems": { "type": "number" }, "interviews": { "type": "number" }, "mirrors": { "type": "number" }, "lastSweep": { "anyOf": [ { "type": "object", "properties": { "sweptAt": { "type": "number" }, "expiredAcknowledgements": { "type": "number" }, "orphanedRecords": { "type": "number" }, "expiredOpenItems": { "type": "number" }, "agedGiftRecords": { "type": "number" }, "droppedInterviews": { "type": "number" }, "staleMirrors": { "type": "number" } }, "required": [ "sweptAt", "expiredAcknowledgements", "orphanedRecords", "expiredOpenItems", "agedGiftRecords", "droppedInterviews", "staleMirrors" ], "additionalProperties": false }, { "type": "null" } ] }, "reconciledOpenItems": { "type": "number" }, "corruption": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "path", "acknowledgements", "giftRecords", "openItems", "interviews", "mirrors", "lastSweep", "reconciledOpenItems", "corruption" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:occasions" ] } }, "/api/occasions/sweep": { "post": { "operationId": "occasions.sweep", "summary": "Run The Approach Sweep Now", "description": "Run one pass immediately: reap expired and orphaned state, find the occasions entering their lead window, batch them into a single message, mirror to the calendar if that is on, and deliver. Delivery goes to every destination in occasions.nudgeChannel, a comma-separated list, so Telegram and the agent both get it, and each is attempted independently, with deliveries[] naming per destination what landed and what did not. Housekeeping runs first and unconditionally, so a machine with nudging turned off still reaps. Returns hold:\"quiet-hours\" or hold:\"disabled\" when it deliberately said nothing, nothing is dropped, it waits.", "tags": [ "occasions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ranAt": { "type": "number" }, "today": { "type": "string" }, "hold": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nudge": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "raisedAt": { "type": "number" }, "subjects": { "type": "array", "items": { "type": "object", "properties": { "occasionId": { "type": "string" }, "title": { "type": "string" }, "person": { "type": "string" }, "kind": { "type": "string", "enum": [ "gift-giving", "remember-only", "neither" ] }, "proximity": { "type": "string", "enum": [ "approaching", "soon", "imminent" ] }, "subject": { "type": "string", "enum": [ "owner", "other", "unattributed" ] }, "acknowledged": { "type": "boolean" } }, "required": [ "occasionId", "title", "person", "kind", "proximity", "subject", "acknowledged" ], "additionalProperties": false } }, "message": { "type": "string" }, "answerable": { "type": "boolean" } }, "required": [ "id", "raisedAt", "subjects", "message", "answerable" ], "additionalProperties": false }, { "type": "null" } ] }, "conflictMessages": { "type": "array", "items": { "type": "string" } }, "resumedInterviews": { "type": "array", "items": { "type": "string" } }, "delivered": { "type": "boolean" }, "deliveryChannel": { "type": "string" }, "deliveryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "delivered": { "type": "boolean" }, "deliveryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failure": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "channel", "delivered", "deliveryId", "failure" ], "additionalProperties": false } }, "mirrored": { "type": "number" }, "housekeeping": { "anyOf": [ { "type": "object", "properties": { "sweptAt": { "type": "number" }, "expiredAcknowledgements": { "type": "number" }, "orphanedRecords": { "type": "number" }, "expiredOpenItems": { "type": "number" }, "agedGiftRecords": { "type": "number" }, "droppedInterviews": { "type": "number" }, "staleMirrors": { "type": "number" } }, "required": [ "sweptAt", "expiredAcknowledgements", "orphanedRecords", "expiredOpenItems", "agedGiftRecords", "droppedInterviews", "staleMirrors" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "ranAt", "today", "hold", "nudge", "conflictMessages", "resumedInterviews", "delivered", "deliveryChannel", "deliveryId", "deliveries", "mirrored", "housekeeping" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:occasions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/panels": { "get": { "operationId": "panels.list", "summary": "List Panels", "description": "Return integration panel descriptors.", "tags": [ "panels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "panels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "open": { "type": "boolean" } }, "required": [ "id", "name", "category", "description", "open" ], "additionalProperties": false } } }, "required": [ "panels" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:panels" ] } }, "/api/panels/open": { "post": { "operationId": "panels.open", "summary": "Open Panel", "description": "Request that a panel be opened in the current TUI session.", "tags": [ "panels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "opened": { "type": "boolean" }, "id": { "type": "string" }, "pane": { "type": "string", "enum": [ "top", "bottom" ] } }, "required": [ "opened", "id", "pane" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:panels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "pane": { "type": "string" } }, "required": [ "id" ], "additionalProperties": true } } } } } }, "/api/payments/budget": { "get": { "operationId": "payments.budget.status", "summary": "Payment Budget Status", "description": "Today's spending pools: the daily item budget, the separate overage budget that covers only unavoidable charges (tax, mandatory fees, and the delivery option actually used), and the tolerance allowance. Each reports its limit, what today has spent, what purchases in flight are holding, and what is left. Includes the calendar day and the timezone it was computed in, the day resets at midnight in daemon.timezone, UTC when unset, and whether this node is the one currently allowed to spend. Totals are recomputed from each spend record's UTC instant rather than counted, so changing the timezone cannot hand back a spent budget.", "tags": [ "payments" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "dayKey": { "type": "string" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "item": { "type": "object", "properties": { "limit": { "type": "number" }, "spent": { "type": "number" }, "reserved": { "type": "number" }, "remaining": { "type": "number" } }, "required": [ "limit", "spent", "reserved", "remaining" ], "additionalProperties": false }, "overage": { "type": "object", "properties": { "limit": { "type": "number" }, "spent": { "type": "number" }, "reserved": { "type": "number" }, "remaining": { "type": "number" } }, "required": [ "limit", "spent", "reserved", "remaining" ], "additionalProperties": false }, "tolerance": { "type": "object", "properties": { "limit": { "type": "number" }, "spent": { "type": "number" }, "reserved": { "type": "number" }, "remaining": { "type": "number" } }, "required": [ "limit", "spent", "reserved", "remaining" ], "additionalProperties": false }, "reservationCount": { "type": "number" }, "isPaymentsLeader": { "type": "boolean" } }, "required": [ "enabled", "dayKey", "timezone", "currency", "item", "overage", "tolerance", "reservationCount", "isPaymentsLeader" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:payments" ] } }, "/api/payments/cards": { "post": { "operationId": "payments.cards.create", "summary": "Add a Payment Card", "description": "Store a card. The number, expiry, CVV and cardholder name go to the daemon secret store, encrypted at rest, under keys derived from the config path; only the label, brand, last four digits, kind and declared issuer cap are kept as config. The response carries the metadata record and never echoes what was submitted, because an echo would be a read path and no read path exists. A virtual card with a hard issuer cap is the recommended configuration: it bounds what any leak could cost to one killable number, which a real card number does not.", "tags": [ "payments" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "card": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string" }, "kind": { "type": "string", "enum": [ "virtual", "real" ] }, "expiryMonth": { "type": "number" }, "expiryYear": { "type": "number" }, "issuerCapMinorUnits": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "addedAt": { "type": "string" }, "materialComplete": { "type": "boolean" } }, "required": [ "id", "label", "brand", "last4", "kind", "expiryMonth", "expiryYear", "issuerCapMinorUnits", "addedAt", "materialComplete" ], "additionalProperties": false } }, "required": [ "card" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "virtual", "real" ] }, "number": { "type": "string" }, "expiryMonth": { "type": "number" }, "expiryYear": { "type": "number" }, "cvv": { "type": "string" }, "cardholderName": { "type": "string" }, "issuerCapMinorUnits": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "label", "kind", "number", "expiryMonth", "expiryYear", "cvv", "cardholderName" ], "additionalProperties": false } } } } }, "get": { "operationId": "payments.cards.list", "summary": "List Payment Cards", "description": "Configured cards, as METADATA ONLY: id, label, brand, last four digits, whether it is a virtual or a real card, expiry month and year, and the issuer spend cap the owner declared for a virtual card (declared, unverifiable by us, and never treated as an enforcement layer of ours). materialComplete reports whether every required secret field is present without revealing any of them. The card number, expiry, CVV and cardholder name live in the daemon secret store and there is no method that returns them.", "tags": [ "payments" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "cards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string" }, "kind": { "type": "string", "enum": [ "virtual", "real" ] }, "expiryMonth": { "type": "number" }, "expiryYear": { "type": "number" }, "issuerCapMinorUnits": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "addedAt": { "type": "string" }, "materialComplete": { "type": "boolean" } }, "required": [ "id", "label", "brand", "last4", "kind", "expiryMonth", "expiryYear", "issuerCapMinorUnits", "addedAt", "materialComplete" ], "additionalProperties": false } }, "defaultCardId": { "type": "string" } }, "required": [ "cards", "defaultCardId" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:payments" ] } }, "/api/payments/cards/{id}": { "delete": { "operationId": "payments.cards.delete", "summary": "Remove a Payment Card", "description": "Delete a card: its config metadata and every secret derived from its config path, reporting how many secret entries were cleared so a partial deletion is visible rather than silent. Deleting the default card leaves payments.defaultCardId empty, which refuses purchases until another card is chosen, the safe direction.", "tags": [ "payments" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" }, "secretsCleared": { "type": "number" } }, "required": [ "id", "deleted", "secretsCleared" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/payments/checkout/begin": { "post": { "operationId": "payments.checkout.begin", "summary": "Buy What Is In This Checkout", "description": "Run a purchase against an open browser page, end to end: the caller reports the checkout's line items, tax, fees and delivery options AS STRINGS plus the refs of the card, address, delivery and place-order controls, and the daemon does the rest. It parses every amount into integer minor units with its own parser (refusing anything ambiguous rather than guessing), checks the cart against what was actually asked for, refuses a recurring charge, runs the taint gate, applies the daily item budget, the per-purchase ceiling and the overage pool, walks the shipping ladder down one rung at a time when the pool cannot cover the preferred tier, sends ONE notice to the configured command-authority channels and runs the window, above budget an approval where silence denies, within budget a veto where silence proceeds, then fills the stored shipping and billing addresses, types the stored card, submits once, records the purchase, debits the budget and reports the completed purchase. Nothing here knows any merchant's markup: the caller identifies the controls on whatever page it is looking at. Every number the owner is shown is re-rendered from the integers this daemon parsed, never from merchant text, and no response field can carry card material.", "tags": [ "payments" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string" }, "purchaseId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merchantOrderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalMinorUnits": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingTierUsed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "steppedDown": { "type": "boolean" }, "challengeStep": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "outcome", "purchaseId", "reason", "merchantOrderId", "totalMinorUnits", "currency", "shippingTierUsed", "steppedDown", "challengeStep" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "merchantDomain": { "type": "string" }, "checkoutUrl": { "type": "string" }, "item": { "type": "string" }, "cardId": { "type": "string" }, "requestedLines": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "quantity": { "type": "number" } }, "required": [ "label", "quantity" ], "additionalProperties": false }, "minItems": 1 }, "lines": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "quantity": { "type": "string" }, "unitPrice": { "type": "string" } }, "required": [ "label", "quantity", "unitPrice" ], "additionalProperties": false }, "minItems": 1 }, "tax": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "label", "amount" ], "additionalProperties": false } }, "shippingOptions": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "cost": { "type": "string" } }, "required": [ "label", "cost" ], "additionalProperties": false }, "minItems": 1 }, "statedTotal": { "type": "string" }, "currency": { "type": "string" }, "orderSummaryText": { "type": "string" }, "cardFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "number", "expiry", "expiryMonth", "expiryYear", "cvv", "cardholderName" ] }, "ref": { "type": "string" } }, "required": [ "field", "ref" ], "additionalProperties": false }, "minItems": 1 }, "addressFields": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shipping", "billing" ] }, "field": { "type": "string", "enum": [ "name", "line1", "line2", "city", "region", "postalCode", "country" ] }, "ref": { "type": "string" } }, "required": [ "kind", "field", "ref" ], "additionalProperties": false } }, "shippingTargets": { "type": "array", "items": { "type": "string" } }, "placeOrderTarget": { "type": "string" }, "preferredTier": { "type": "string", "enum": [ "normal", "fast", "fastest" ] }, "expirySeparator": { "type": "string" }, "twoDigitYear": { "type": "boolean" }, "requestedMax": { "type": "string" } }, "required": [ "sessionId", "pageId", "merchantDomain", "checkoutUrl", "item", "cardId", "requestedLines", "lines", "shippingOptions", "cardFields", "placeOrderTarget" ], "additionalProperties": false } } } } } }, "/api/payments/checkout/fill-card": { "post": { "operationId": "payments.checkout.fillCard", "summary": "Fill the Card into a Checkout", "description": "Have the daemon type the stored card into the payment fields of an open browser page. Takes the browser session, the page, and a list of {field, ref} targets naming where each part of the card goes, the caller identifies the fields on whatever checkout it is looking at, so the daemon needs no knowledge of any merchant. The response is the list of field NAMES that were filled plus a boolean; it never carries the value, its length, or a masked form, and a failure names the field that did not accept input rather than what was typed into it. Refused unless a purchase decision is already in flight on that exact page and the page is still on the registrable domain the purchase was decided against, so the card is typed as part of an approved checkout or not at all. Also refused when the browser has no card-material redaction installed, because a snapshot taken afterwards would otherwise hand back what was just typed.", "tags": [ "payments" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "filled": { "type": "array", "items": { "type": "string" } }, "failedField": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "ok", "filled", "failedField", "reason" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "pageId": { "type": "string" }, "targets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "number", "expiry", "expiryMonth", "expiryYear", "cvv", "cardholderName" ] }, "ref": { "type": "string" } }, "required": [ "field", "ref" ], "additionalProperties": false }, "minItems": 1 }, "expirySeparator": { "type": "string" }, "twoDigitYear": { "type": "boolean" } }, "required": [ "sessionId", "pageId", "targets" ], "additionalProperties": false } } } } } }, "/api/payments/purchases": { "get": { "operationId": "payments.purchases.list", "summary": "List Purchases", "description": "The purchase audit ledger: what was bought, from which merchant registrable domain, how much (item, tax, fees and delivery separately), which budget pool each part drew on, which delivery tier was requested and which was actually used, whether the shipping ladder stepped it down, which window ran and how it ended, which command-authority channel answered, and the outcome. Reconcilable against a card statement. Never contains a card number, expiry or CVV. A refund is recorded here for reconciliation and credits no pool, a refund on day five refilling day five would be permission to buy again that nobody granted.", "tags": [ "payments" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchases": { "type": "array", "items": { "type": "object", "properties": { "purchaseId": { "type": "string" }, "atUtc": { "type": "string" }, "dayKey": { "type": "string" }, "timezone": { "type": "string" }, "merchantDomain": { "type": "string" }, "item": { "type": "string" }, "currency": { "type": "string" }, "itemMinorUnits": { "type": "number" }, "taxMinorUnits": { "type": "number" }, "feesMinorUnits": { "type": "number" }, "shippingMinorUnits": { "type": "number" }, "totalMinorUnits": { "type": "number" }, "shippingTierRequested": { "type": "string" }, "shippingTierUsed": { "type": "string" }, "steppedDown": { "type": "boolean" }, "itemPoolDraw": { "type": "number" }, "overagePoolDraw": { "type": "number" }, "tolerancePoolDraw": { "type": "number" }, "cardLast4": { "type": "string" }, "windowKind": { "type": "string" }, "windowOutcome": { "type": "string" }, "answeredBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "type": "string" }, "refusalReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merchantOrderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merchantRecognised": { "type": "boolean" }, "merchantQualifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merchantDiscovered": { "type": "boolean" } }, "required": [ "purchaseId", "atUtc", "dayKey", "timezone", "merchantDomain", "item", "currency", "itemMinorUnits", "taxMinorUnits", "feesMinorUnits", "shippingMinorUnits", "totalMinorUnits", "shippingTierRequested", "shippingTierUsed", "steppedDown", "itemPoolDraw", "overagePoolDraw", "tolerancePoolDraw", "cardLast4", "windowKind", "windowOutcome", "answeredBy", "outcome", "refusalReason", "merchantOrderId", "refundedAt", "merchantRecognised", "merchantQualifier", "merchantDiscovered" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "purchases", "total" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:payments" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "dayKey", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/principals": { "post": { "operationId": "principals.create", "summary": "Create Principal", "description": "Create a named principal from a name, kind, and optional channel identities. Fails with a conflict when any identity is already mapped to a different principal.", "tags": [ "principals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, "identities": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "value": { "type": "string" } }, "required": [ "channel", "value" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "kind", "identities", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "principal" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:principals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, "identities": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "value": { "type": "string" } }, "required": [ "channel", "value" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "name", "kind" ], "additionalProperties": false } } } } }, "get": { "operationId": "principals.list", "summary": "List Principals", "description": "Return every named principal in the registry with its channel identities.", "tags": [ "principals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "principals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, "identities": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "value": { "type": "string" } }, "required": [ "channel", "value" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "kind", "identities", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "principals" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:principals" ] } }, "/api/principals/{principalId}": { "delete": { "operationId": "principals.delete", "summary": "Delete Principal", "description": "Permanently delete a principal. Returns { deleted: false } when no principal with that id existed, an honest boolean, never a 200 that pretends a phantom principal was removed.", "tags": [ "principals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "principalId": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "principalId", "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:principals" ], "x-dangerous": true, "parameters": [ { "name": "principalId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "get": { "operationId": "principals.get", "summary": "Get Principal", "description": "Return one principal by id. Returns 404 when no principal with that id exists.", "tags": [ "principals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, "identities": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "value": { "type": "string" } }, "required": [ "channel", "value" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "kind", "identities", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "principal" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:principals" ], "parameters": [ { "name": "principalId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/principals/resolve": { "post": { "operationId": "principals.resolve", "summary": "Resolve Sender Identity", "description": "Resolve a channel-specific sender identity ({channel, value}) to the named principal it belongs to. An unmapped identity resolves to the shared unknown principal with known:false, the registry never guesses.", "tags": [ "principals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, "identities": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "value": { "type": "string" } }, "required": [ "channel", "value" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "kind", "identities", "createdAt", "updatedAt" ], "additionalProperties": false }, "known": { "type": "boolean" } }, "required": [ "principal", "known" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:principals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string" }, "value": { "type": "string" } }, "required": [ "channel", "value" ], "additionalProperties": false } } } } } }, "/api/principals/{principalId}/update": { "post": { "operationId": "principals.update", "summary": "Update Principal", "description": "Update a principal's name, kind, identities, and/or metadata. Absent fields are left unchanged; supplying identities replaces the set. Fails with a conflict when an identity is already mapped to a different principal.", "tags": [ "principals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, "identities": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "value": { "type": "string" } }, "required": [ "channel", "value" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "name", "kind", "identities", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "principal" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:principals" ], "parameters": [ { "name": "principalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "principalId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, "identities": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "value": { "type": "string" } }, "required": [ "channel", "value" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "principalId" ], "additionalProperties": false } } } } } }, "/api/profile/append": { "post": { "operationId": "profile.append", "summary": "Append Profile Note", "description": "Add one prose bullet to a section, carrying its provenance suffix. Same three-layer gate as profile.set. A section that does not exist is created at the end of the document; a section the owner renamed is matched case-insensitively rather than duplicated.", "tags": [ "profile" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "fieldId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "section": { "type": "string" }, "label": { "type": "string" }, "superseded": { "type": "boolean" } }, "required": [ "kind", "section", "label", "superseded" ], "additionalProperties": false } }, "disclosure": { "type": "string" } }, "required": [ "ok", "changes", "disclosure" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:profile" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "text": { "type": "string" }, "surface": { "type": "string" }, "said": { "type": "string" }, "authority": { "type": "string" } }, "required": [ "section", "text", "surface", "said", "authority" ], "additionalProperties": false } } } } } }, "/api/profile/forget": { "post": { "operationId": "profile.forget", "summary": "Forget Profile Line", "description": "Delete a mechanical field and every retained history comment for it, or one prose line addressed by its section plus its exact text. Never by line position: the owner edits this file himself, so an index taken from an earlier read may name a different line by the time the delete arrives. Text that no longer matches removes nothing and says so, rather than deleting the nearest thing. No tombstone, no deleted flag, no retention window, delete means delete. Forgetting something that was not there reports that honestly instead of returning success. Authority-gated exactly like a write: an injection that cannot add a fact must not be able to remove one.", "tags": [ "profile" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "fieldId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "section": { "type": "string" }, "label": { "type": "string" }, "superseded": { "type": "boolean" } }, "required": [ "kind", "section", "label", "superseded" ], "additionalProperties": false } }, "disclosure": { "type": "string" } }, "required": [ "ok", "changes", "disclosure" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:profile" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldId": { "type": "string" }, "section": { "type": "string" }, "text": { "type": "string" }, "authority": { "type": "string" } }, "required": [ "authority" ], "additionalProperties": false } } } } } }, "/api/profile/fields/{fieldId}": { "get": { "operationId": "profile.get", "summary": "Get Profile Field", "description": "Return one mechanical field by id (e.g. commerce.shippingAddress). Answers present:false for a field the owner has not recorded rather than inventing a value, and returns an invalid value verbatim with its reason instead of hiding it. A closed-tier field carries the one-line disclosure the reply should show.", "tags": [ "profile" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldId": { "type": "string" }, "present": { "type": "boolean" }, "field": { "type": "object", "properties": { "fieldId": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "valid": { "type": "boolean" }, "section": { "type": "string" }, "invalidReason": { "type": "string" }, "provenance": { "type": "object", "properties": { "surface": { "type": "string" }, "date": { "type": "string" }, "said": { "type": "string" } }, "required": [ "surface", "date", "said" ], "additionalProperties": false } }, "required": [ "fieldId", "label", "value", "valid", "section" ], "additionalProperties": false }, "disclosure": { "type": "string" } }, "required": [ "fieldId", "present", "disclosure" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:profile" ], "parameters": [ { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/profile/person": { "post": { "operationId": "profile.person", "summary": "Get Person From Profile", "description": "Return the People lines matching one name. Takes a NAME by design and has no enumerate-all counterpart: a People line may reach outbound content only when the owner named that person in this turn's instruction, and the only lookup that exists taking a name is what makes that structural rather than a matter of model judgement.", "tags": [ "profile" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineIndex": { "type": "number" }, "section": { "type": "string" }, "text": { "type": "string" }, "provenance": { "type": "object", "properties": { "surface": { "type": "string" }, "date": { "type": "string" }, "said": { "type": "string" } }, "required": [ "surface", "date", "said" ], "additionalProperties": false } }, "required": [ "lineIndex", "section", "text" ], "additionalProperties": false } }, "disclosure": { "type": "string" } }, "required": [ "name", "lines", "disclosure" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:profile" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/api/profile/fields/{fieldId}/provenance": { "get": { "operationId": "profile.provenance", "summary": "Get Profile Provenance", "description": "Answer \"where did you get that?\" for one field: the surface, the date and the owner's verbatim words, plus every superseded predecessor still retained as a history comment. A field the owner typed by hand reports handEdited:true and no provenance, rather than being dressed up as a recorded source.", "tags": [ "profile" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldId": { "type": "string" }, "present": { "type": "boolean" }, "handEdited": { "type": "boolean" }, "provenance": { "anyOf": [ { "type": "object", "properties": { "surface": { "type": "string" }, "date": { "type": "string" }, "said": { "type": "string" } }, "required": [ "surface", "date", "said" ], "additionalProperties": false }, { "type": "null" } ] }, "superseded": { "type": "array", "items": { "type": "object", "properties": { "lineIndex": { "type": "number" }, "fieldId": { "type": "string" }, "section": { "type": "string" }, "text": { "type": "string" }, "value": { "type": "string" }, "supersededOn": { "type": "string" }, "previousLine": { "type": "string" }, "provenance": { "type": "object", "properties": { "surface": { "type": "string" }, "date": { "type": "string" }, "said": { "type": "string" } }, "required": [ "surface", "date", "said" ], "additionalProperties": false } }, "required": [ "lineIndex", "fieldId", "section", "text", "value", "supersededOn", "previousLine" ], "additionalProperties": false } } }, "required": [ "fieldId", "present", "handEdited", "provenance", "superseded" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:profile" ], "parameters": [ { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/profile": { "get": { "operationId": "profile.read", "summary": "Read Owner Profile", "description": "Return the whole owner profile, by section, with each section's tier and every mechanical field's validity. This is the answer to \"what do you know about me?\" and is the ONE read that returns closed-tier content in bulk. It carries its own scope, read:profile-document, so a token issued to a composition path can hold read:profile for the named lookups (get/person/provenance/status) without also being able to ask for everything. The two are unrelated names rather than a hierarchy: scope matching is exact, `*`, or a `prefix:*` wildcard, so a caller wanting both lists both.", "tags": [ "profile" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "object", "properties": { "kind": { "type": "string" }, "path": { "type": "string" }, "exists": { "type": "boolean" }, "lineCount": { "type": "number" }, "fieldCount": { "type": "number" }, "proseLineCount": { "type": "number" }, "sections": { "type": "array", "items": { "type": "string" } }, "invalidFields": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "fieldId", "reason" ], "additionalProperties": false } }, "reason": { "type": "string" } }, "required": [ "kind", "path" ], "additionalProperties": false }, "sections": { "type": "array", "items": { "type": "object", "properties": { "heading": { "type": "string" }, "tier": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "valid": { "type": "boolean" }, "invalidReason": { "type": "string" }, "provenance": { "type": "object", "properties": { "surface": { "type": "string" }, "date": { "type": "string" }, "said": { "type": "string" } }, "required": [ "surface", "date", "said" ], "additionalProperties": false } }, "required": [ "fieldId", "label", "value", "valid" ], "additionalProperties": false } }, "prose": { "type": "array", "items": { "type": "object", "properties": { "lineIndex": { "type": "number" }, "section": { "type": "string" }, "text": { "type": "string" }, "provenance": { "type": "object", "properties": { "surface": { "type": "string" }, "date": { "type": "string" }, "said": { "type": "string" } }, "required": [ "surface", "date", "said" ], "additionalProperties": false } }, "required": [ "lineIndex", "section", "text" ], "additionalProperties": false } } }, "required": [ "heading", "tier", "fields", "prose" ], "additionalProperties": false } } }, "required": [ "state", "sections" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:profile-document" ] } }, "/api/profile/set": { "post": { "operationId": "profile.set", "summary": "Set Profile Field", "description": "Record or correct one mechanical field, moving any previous value into a retained history comment. Refused unless the caller carries owner-direct authority AND the proposed value does not overlap untrusted content read this turn AND a verbatim quote of what the owner said is supplied. A caller declaring the call was not an explicit user request is refused before any of that.", "tags": [ "profile" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "fieldId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "section": { "type": "string" }, "label": { "type": "string" }, "superseded": { "type": "boolean" } }, "required": [ "kind", "section", "label", "superseded" ], "additionalProperties": false } }, "disclosure": { "type": "string" } }, "required": [ "ok", "changes", "disclosure" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:profile" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldId": { "type": "string" }, "value": { "type": "string" }, "surface": { "type": "string" }, "said": { "type": "string" }, "authority": { "type": "string" } }, "required": [ "fieldId", "value", "surface", "said", "authority" ], "additionalProperties": false } } } } } }, "/api/profile/status": { "get": { "operationId": "profile.status", "summary": "Owner Profile Status", "description": "Diagnostics for the profile: whether it loaded, the file path, the section names, line/field/prose counts, and every mechanical value that did not validate WITH ITS REASON. It never returns a value, that is what makes it safe in a support bundle, and it is asserted by test. An unreadable file reports unavailable with the reason rather than an empty profile.", "tags": [ "profile" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "path": { "type": "string" }, "exists": { "type": "boolean" }, "lineCount": { "type": "number" }, "fieldCount": { "type": "number" }, "proseLineCount": { "type": "number" }, "sections": { "type": "array", "items": { "type": "string" } }, "invalidFields": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "fieldId", "reason" ], "additionalProperties": false } }, "reason": { "type": "string" } }, "required": [ "kind", "path" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:profile" ] } }, "/api/profile/undo": { "post": { "operationId": "profile.undo", "summary": "Undo Profile Correction", "description": "Promote a field's most recent superseded value back to the active line, so a wrong correction is recoverable. Authority-gated like every other mutation.", "tags": [ "profile" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "fieldId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "section": { "type": "string" }, "label": { "type": "string" }, "superseded": { "type": "boolean" } }, "required": [ "kind", "section", "label", "superseded" ], "additionalProperties": false } }, "disclosure": { "type": "string" } }, "required": [ "ok", "changes", "disclosure" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:profile" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldId": { "type": "string" }, "authority": { "type": "string" } }, "required": [ "fieldId", "authority" ], "additionalProperties": false } } } } } }, "/api/models/current": { "get": { "operationId": "models.current.get", "summary": "Current Model", "description": "The model this daemon would use for a turn right now, with whether its provider is actually configured and by which authentication route. `model` is null when nothing is selected, which is a real state, not an error, and a caller rendering a picker needs to tell it from a selection whose provider has lost its credentials. `effort` is the persisted reasoning level, null when none has been set explicitly.", "tags": [ "providers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "object", "properties": { "registryKey": { "type": "string" }, "provider": { "type": "string" }, "id": { "type": "string" } }, "required": [ "registryKey", "provider", "id" ], "additionalProperties": false }, { "type": "null" } ] }, "configured": { "type": "boolean" }, "configuredVia": { "type": "string", "enum": [ "env", "secrets", "subscription", "anonymous" ] }, "routes": { "type": "array", "items": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "api-key", "secret-ref", "service-oauth", "subscription-oauth", "anonymous", "none" ] }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "usable": { "type": "boolean" }, "freshness": { "type": "string", "enum": [ "healthy", "expiring", "expired", "pending", "unconfigured" ] }, "detail": { "type": "string" }, "envVars": { "type": "array", "items": { "type": "string" } }, "secretKeys": { "type": "array", "items": { "type": "string" } }, "serviceNames": { "type": "array", "items": { "type": "string" } }, "providerId": { "type": "string" }, "repairHints": { "type": "array", "items": { "type": "string" } } }, "required": [ "route", "label", "configured" ], "additionalProperties": false } }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "model", "configured" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:providers" ] }, "patch": { "operationId": "models.current.set", "summary": "Switch the Current Model", "description": "Switch the daemon's current model live, by the registry key `models.list` returns. The switch applies to the next turn on every surface this daemon serves and is persisted, so it survives a restart; `persisted` says whether the write to settings succeeded. An unknown key is refused with MODEL_NOT_FOUND and a provider with no usable credentials with PROVIDER_NOT_CONFIGURED, naming the environment variables it looked for, a caller must not have to guess which of the two happened. An optional `effort` persists a reasoning level with the selection: it is validated against the known severity ladder here, and each turn maps it onto the active model's real options, snapping down and never promoting.", "tags": [ "providers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "object", "properties": { "registryKey": { "type": "string" }, "provider": { "type": "string" }, "id": { "type": "string" } }, "required": [ "registryKey", "provider", "id" ], "additionalProperties": false }, { "type": "null" } ] }, "configured": { "type": "boolean" }, "configuredVia": { "type": "string", "enum": [ "env", "secrets", "subscription", "anonymous" ] }, "routes": { "type": "array", "items": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "api-key", "secret-ref", "service-oauth", "subscription-oauth", "anonymous", "none" ] }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "usable": { "type": "boolean" }, "freshness": { "type": "string", "enum": [ "healthy", "expiring", "expired", "pending", "unconfigured" ] }, "detail": { "type": "string" }, "envVars": { "type": "array", "items": { "type": "string" } }, "secretKeys": { "type": "array", "items": { "type": "string" } }, "serviceNames": { "type": "array", "items": { "type": "string" } }, "providerId": { "type": "string" }, "repairHints": { "type": "array", "items": { "type": "string" } } }, "required": [ "route", "label", "configured" ], "additionalProperties": false } }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "persisted": { "type": "boolean" } }, "required": [ "model", "configured", "persisted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:providers" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "registryKey": { "type": "string" }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "registryKey" ], "additionalProperties": false } } } } } }, "/api/models": { "get": { "operationId": "models.list", "summary": "Model Catalog", "description": "Every provider this daemon knows about with the models it offers, whether it is configured, and how it was configured. A GET also triggers the TTL-respecting live-discovery re-check that the terminal's model picker triggers on open, so a locally served model that appeared since the last read shows up on the next one. `currentModel` is the daemon's current selection, or null when nothing is selected. `secretsResolutionSkipped` is true when secret-backed credentials were not resolved for this read, so a caller can tell \"not configured\" from \"not checked\". Each model that reasons carries `reasoningOptions`: the levels it actually offers and which source resolved them; a model with no entry does not reason at all.", "tags": [ "providers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "configuredVia": { "type": "string", "enum": [ "env", "secrets", "subscription", "anonymous" ] }, "envVars": { "type": "array", "items": { "type": "string" } }, "routes": { "type": "array", "items": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "api-key", "secret-ref", "service-oauth", "subscription-oauth", "anonymous", "none" ] }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "usable": { "type": "boolean" }, "freshness": { "type": "string", "enum": [ "healthy", "expiring", "expired", "pending", "unconfigured" ] }, "detail": { "type": "string" }, "envVars": { "type": "array", "items": { "type": "string" } }, "secretKeys": { "type": "array", "items": { "type": "string" } }, "serviceNames": { "type": "array", "items": { "type": "string" } }, "providerId": { "type": "string" }, "repairHints": { "type": "array", "items": { "type": "string" } } }, "required": [ "route", "label", "configured" ], "additionalProperties": false } }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "registryKey": { "type": "string" }, "provider": { "type": "string" }, "label": { "type": "string" }, "contextWindow": { "type": "number" }, "reasoningOptions": { "type": "object", "properties": { "levels": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "catalog", "declared", "family", "fallback" ] } }, "required": [ "levels", "source" ], "additionalProperties": false } }, "required": [ "id", "registryKey", "provider" ], "additionalProperties": false } } }, "required": [ "id", "label", "configured", "envVars", "models" ], "additionalProperties": false } }, "currentModel": { "anyOf": [ { "type": "object", "properties": { "registryKey": { "type": "string" }, "provider": { "type": "string" }, "id": { "type": "string" } }, "required": [ "registryKey", "provider", "id" ], "additionalProperties": false }, { "type": "null" } ] }, "secretsResolutionSkipped": { "type": "boolean" } }, "required": [ "providers", "currentModel", "secretsResolutionSkipped" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:providers" ] } }, "/api/providers/{providerId}": { "get": { "operationId": "providers.get", "summary": "Provider Snapshot", "description": "Return runtime metadata for a single provider.", "tags": [ "providers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "active": { "type": "boolean" }, "modelCount": { "type": "number" }, "runtime": { "type": "object", "properties": { "auth": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "api-key", "oauth", "anonymous", "none" ] }, "configured": { "type": "boolean" }, "detail": { "type": "string" }, "envVars": { "type": "array", "items": { "type": "string" } }, "routes": { "type": "array", "items": { "type": "object", "properties": { "route": { "type": "string" }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "usable": { "type": "boolean" }, "freshness": { "type": "string" }, "detail": { "type": "string" }, "envVars": { "type": "array", "items": { "type": "string" } }, "secretKeys": { "type": "array", "items": { "type": "string" } }, "serviceNames": { "type": "array", "items": { "type": "string" } }, "providerId": { "type": "string" }, "repairHints": { "type": "array", "items": { "type": "string" } } }, "required": [ "route", "label", "configured" ], "additionalProperties": true } } }, "required": [ "mode", "configured" ], "additionalProperties": true }, "models": { "type": "object", "properties": { "defaultModel": { "type": "string" }, "models": { "type": "array", "items": { "type": "string" } }, "embeddingModel": { "type": "string" }, "embeddingDimensions": { "type": "number" }, "aliases": { "type": "array", "items": { "type": "string" } }, "suppressedModelRegistryKeys": { "type": "array", "items": { "type": "string" } } }, "required": [ "models" ], "additionalProperties": true }, "usage": { "type": "object", "properties": { "streaming": { "type": "boolean" }, "toolCalling": { "type": "boolean" }, "parallelTools": { "type": "boolean" }, "promptCaching": { "type": "boolean" }, "cost": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "catalog", "provider", "none" ] }, "currency": { "type": "string" }, "inputPerMillionTokens": { "type": "number" }, "outputPerMillionTokens": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "source" ], "additionalProperties": true }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "streaming", "toolCalling", "parallelTools" ], "additionalProperties": true }, "policy": { "type": "object", "properties": { "local": { "type": "boolean" }, "dataRetention": { "type": "string" }, "streamProtocol": { "type": "string" }, "reasoningMode": { "type": "string" }, "supportedReasoningEfforts": { "type": "array", "items": { "type": "string" } }, "cacheStrategy": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "notes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "registryKey": { "type": "string" }, "displayName": { "type": "string" }, "selectable": { "type": "boolean" }, "contextWindow": { "type": "number" }, "tier": { "type": "string" }, "pricing": { "type": "object", "properties": { "inputPerMillionTokens": { "type": "number" }, "outputPerMillionTokens": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "source": { "type": "string", "enum": [ "user", "provider", "catalog" ] }, "asOf": { "type": "string" } }, "required": [ "inputPerMillionTokens", "outputPerMillionTokens", "currency", "source" ], "additionalProperties": false } }, "required": [ "id", "registryKey", "displayName", "selectable", "contextWindow" ], "additionalProperties": true } } }, "required": [ "providerId", "active", "modelCount", "runtime", "models" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:providers" ], "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/providers": { "get": { "operationId": "providers.list", "summary": "Providers List", "description": "Return runtime provider metadata, policy hooks, and priced model summaries.", "tags": [ "providers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "providerId": { "type": "string" }, "active": { "type": "boolean" }, "modelCount": { "type": "number" }, "runtime": { "type": "object", "properties": { "auth": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "api-key", "oauth", "anonymous", "none" ] }, "configured": { "type": "boolean" }, "detail": { "type": "string" }, "envVars": { "type": "array", "items": { "type": "string" } }, "routes": { "type": "array", "items": { "type": "object", "properties": { "route": { "type": "string" }, "label": { "type": "string" }, "configured": { "type": "boolean" }, "usable": { "type": "boolean" }, "freshness": { "type": "string" }, "detail": { "type": "string" }, "envVars": { "type": "array", "items": { "type": "string" } }, "secretKeys": { "type": "array", "items": { "type": "string" } }, "serviceNames": { "type": "array", "items": { "type": "string" } }, "providerId": { "type": "string" }, "repairHints": { "type": "array", "items": { "type": "string" } } }, "required": [ "route", "label", "configured" ], "additionalProperties": true } } }, "required": [ "mode", "configured" ], "additionalProperties": true }, "models": { "type": "object", "properties": { "defaultModel": { "type": "string" }, "models": { "type": "array", "items": { "type": "string" } }, "embeddingModel": { "type": "string" }, "embeddingDimensions": { "type": "number" }, "aliases": { "type": "array", "items": { "type": "string" } }, "suppressedModelRegistryKeys": { "type": "array", "items": { "type": "string" } } }, "required": [ "models" ], "additionalProperties": true }, "usage": { "type": "object", "properties": { "streaming": { "type": "boolean" }, "toolCalling": { "type": "boolean" }, "parallelTools": { "type": "boolean" }, "promptCaching": { "type": "boolean" }, "cost": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "catalog", "provider", "none" ] }, "currency": { "type": "string" }, "inputPerMillionTokens": { "type": "number" }, "outputPerMillionTokens": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "source" ], "additionalProperties": true }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "streaming", "toolCalling", "parallelTools" ], "additionalProperties": true }, "policy": { "type": "object", "properties": { "local": { "type": "boolean" }, "dataRetention": { "type": "string" }, "streamProtocol": { "type": "string" }, "reasoningMode": { "type": "string" }, "supportedReasoningEfforts": { "type": "array", "items": { "type": "string" } }, "cacheStrategy": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "notes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "registryKey": { "type": "string" }, "displayName": { "type": "string" }, "selectable": { "type": "boolean" }, "contextWindow": { "type": "number" }, "tier": { "type": "string" }, "pricing": { "type": "object", "properties": { "inputPerMillionTokens": { "type": "number" }, "outputPerMillionTokens": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "source": { "type": "string", "enum": [ "user", "provider", "catalog" ] }, "asOf": { "type": "string" } }, "required": [ "inputPerMillionTokens", "outputPerMillionTokens", "currency", "source" ], "additionalProperties": false } }, "required": [ "id", "registryKey", "displayName", "selectable", "contextWindow" ], "additionalProperties": true } } }, "required": [ "providerId", "active", "modelCount", "runtime", "models" ], "additionalProperties": false } } }, "required": [ "providers" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:providers" ] } }, "/api/providers/{providerId}/usage": { "get": { "operationId": "providers.usage.get", "summary": "Provider Usage", "description": "Return usage and pricing posture for a single provider.", "tags": [ "providers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "active": { "type": "boolean" }, "currentModelRegistryKey": { "type": "string" }, "pricingSource": { "type": "string", "enum": [ "user", "catalog", "provider", "mixed", "none" ] }, "pricingAsOf": { "type": "string" }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "registryKey": { "type": "string" }, "displayName": { "type": "string" }, "selectable": { "type": "boolean" }, "contextWindow": { "type": "number" }, "tier": { "type": "string" }, "pricing": { "type": "object", "properties": { "inputPerMillionTokens": { "type": "number" }, "outputPerMillionTokens": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "source": { "type": "string", "enum": [ "user", "provider", "catalog" ] }, "asOf": { "type": "string" } }, "required": [ "inputPerMillionTokens", "outputPerMillionTokens", "currency", "source" ], "additionalProperties": false } }, "required": [ "id", "registryKey", "displayName", "selectable", "contextWindow" ], "additionalProperties": true } }, "usage": { "type": "object", "properties": { "streaming": { "type": "boolean" }, "toolCalling": { "type": "boolean" }, "parallelTools": { "type": "boolean" }, "promptCaching": { "type": "boolean" }, "cost": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "catalog", "provider", "none" ] }, "currency": { "type": "string" }, "inputPerMillionTokens": { "type": "number" }, "outputPerMillionTokens": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "source" ], "additionalProperties": true }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "streaming", "toolCalling", "parallelTools" ], "additionalProperties": true } }, "required": [ "providerId", "active", "pricingSource", "models", "usage" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:providers" ], "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/stepup/challenge": { "post": { "operationId": "stepup.challenge.mint", "summary": "Mint Step-up Challenge", "description": "Issue a short-lived, single-use WebAuthn challenge bound to the calling session/rendezvous. A surface passes it to navigator.credentials.get and returns the assertion on its next mutating relay call. The freshness window (ttlMs) is clamped to 5s–300s (default 120s).", "tags": [ "relay" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "challenge": { "type": "string" }, "expiresAt": { "type": "number" } }, "required": [ "challengeId", "challenge", "expiresAt" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:relay" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rendezvousId": { "type": "string" }, "sessionId": { "type": "string" }, "ttlMs": { "type": "number" } }, "additionalProperties": false } } } } } }, "/api/stepup/credentials": { "post": { "operationId": "stepup.credentials.register", "summary": "Register Step-up Credential", "description": "Store a WebAuthn (passkey) credential for relay step-up, its credentialId, COSE public key, and starting signature counter, and set the deployment policy (relying-party id, allowed origins, user-verification requirement). Admin/local-only: registering a step-up credential is itself a sensitive act. Self-hosted deployments register the credential directly ('none' attestation).", "tags": [ "relay" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "properties": { "credentialId": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "number" }, "signCount": { "type": "number" } }, "required": [ "credentialId", "createdAt", "signCount" ], "additionalProperties": false } }, "required": [ "credential" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:relay" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rpId": { "type": "string" }, "origin": { "type": "string" }, "credentialId": { "type": "string" }, "publicKeyCose": { "type": "string" }, "signCount": { "type": "number" }, "userVerification": { "type": "string", "enum": [ "required", "preferred", "discouraged" ] }, "label": { "type": "string" } }, "required": [ "rpId", "origin", "credentialId", "publicKeyCose" ], "additionalProperties": false } } } } } }, "/api/remote/node-host/contract": { "get": { "operationId": "remote.node_host.contract", "summary": "Node Host Contract", "description": "Return the distributed node/device host API contract.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contract": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "transport": { "type": "string" }, "basePath": { "type": "string" }, "peerKinds": { "type": "array", "items": { "type": "string", "enum": [ "node", "device" ] } }, "workTypes": { "type": "array", "items": { "type": "string", "enum": [ "invoke", "status.request", "location.request", "session.message", "automation.run", "device.capability" ] } }, "scopes": { "type": "array", "items": { "type": "string" } }, "recommendedHeartbeatMs": { "type": "number" }, "recommendedWorkPullMs": { "type": "number" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "path": { "type": "string" }, "auth": { "type": "string", "enum": [ "none", "bearer-peer-token", "bearer-operator-token" ] }, "description": { "type": "string" }, "requiredScope": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "outputSchema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "method", "path", "auth", "description" ], "additionalProperties": true } }, "workCompletionStatuses": { "type": "array", "items": { "type": "string", "enum": [ "queued", "claimed", "completed", "failed", "cancelled", "expired" ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "schemaVersion", "transport", "basePath", "peerKinds", "workTypes", "scopes", "recommendedHeartbeatMs", "recommendedWorkPullMs", "endpoints", "workCompletionStatuses", "metadata" ], "additionalProperties": false } }, "required": [ "contract" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:remote" ] } }, "/api/remote/pair/requests/{requestId}/approve": { "post": { "operationId": "remote.pair.requests.approve", "summary": "Approve Remote Pair Request", "description": "Approve a pending remote pair request.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string" }, "peerKind": { "type": "string", "enum": [ "node", "device" ] }, "requestedId": { "type": "string" }, "label": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "requestedBy": { "type": "string", "enum": [ "remote", "operator" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "verified", "rejected", "expired" ] }, "challengePreview": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "approvedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "rejectedAt": { "type": "number" }, "expiresAt": { "type": "number" }, "peerId": { "type": "string" }, "remoteAddress": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "peerKind", "requestedId", "label", "capabilities", "commands", "requestedBy", "status", "challengePreview", "createdAt", "updatedAt", "expiresAt", "metadata" ], "additionalProperties": true }, "peer": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "node", "device" ] }, "label": { "type": "string" }, "requestedId": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "object", "additionalProperties": { "type": "boolean" } }, "status": { "type": "string", "enum": [ "paired", "connected", "idle", "disconnected", "revoked" ] }, "pairedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "lastConnectedAt": { "type": "number" }, "lastDisconnectedAt": { "type": "number" }, "lastRemoteAddress": { "type": "string" }, "activeTokenId": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "issuedAt": { "type": "number" }, "lastUsedAt": { "type": "number" }, "rotatedAt": { "type": "number" }, "revokedAt": { "type": "number" }, "fingerprint": { "type": "string" } }, "required": [ "id", "label", "scopes", "issuedAt", "fingerprint" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "requestedId", "capabilities", "commands", "status", "pairedAt", "tokens", "metadata" ], "additionalProperties": true } }, "required": [ "request", "peer" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:remote" ], "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "note": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "requestId" ], "additionalProperties": true } } } } } }, "/api/remote/pair/requests": { "get": { "operationId": "remote.pair.requests.list", "summary": "List Remote Pair Requests", "description": "Return pending remote pair requests.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "peerKind": { "type": "string", "enum": [ "node", "device" ] }, "requestedId": { "type": "string" }, "label": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "requestedBy": { "type": "string", "enum": [ "remote", "operator" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "verified", "rejected", "expired" ] }, "challengePreview": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "approvedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "rejectedAt": { "type": "number" }, "expiresAt": { "type": "number" }, "peerId": { "type": "string" }, "remoteAddress": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "peerKind", "requestedId", "label", "capabilities", "commands", "requestedBy", "status", "challengePreview", "createdAt", "updatedAt", "expiresAt", "metadata" ], "additionalProperties": true } } }, "required": [ "requests" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:remote" ] } }, "/api/remote/pair/requests/{requestId}/reject": { "post": { "operationId": "remote.pair.requests.reject", "summary": "Reject Remote Pair Request", "description": "Reject a pending remote pair request.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string" }, "peerKind": { "type": "string", "enum": [ "node", "device" ] }, "requestedId": { "type": "string" }, "label": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "requestedBy": { "type": "string", "enum": [ "remote", "operator" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "verified", "rejected", "expired" ] }, "challengePreview": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "approvedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "rejectedAt": { "type": "number" }, "expiresAt": { "type": "number" }, "peerId": { "type": "string" }, "remoteAddress": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "peerKind", "requestedId", "label", "capabilities", "commands", "requestedBy", "status", "challengePreview", "createdAt", "updatedAt", "expiresAt", "metadata" ], "additionalProperties": true } }, "required": [ "request" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:remote" ], "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "note": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "requestId" ], "additionalProperties": true } } } } } }, "/api/remote/peers/{peerId}/disconnect": { "post": { "operationId": "remote.peers.disconnect", "summary": "Disconnect Remote Peer", "description": "Disconnect a remote peer.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "peer": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "node", "device" ] }, "label": { "type": "string" }, "requestedId": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "object", "additionalProperties": { "type": "boolean" } }, "status": { "type": "string", "enum": [ "paired", "connected", "idle", "disconnected", "revoked" ] }, "pairedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "lastConnectedAt": { "type": "number" }, "lastDisconnectedAt": { "type": "number" }, "lastRemoteAddress": { "type": "string" }, "activeTokenId": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "issuedAt": { "type": "number" }, "lastUsedAt": { "type": "number" }, "rotatedAt": { "type": "number" }, "revokedAt": { "type": "number" }, "fingerprint": { "type": "string" } }, "required": [ "id", "label", "scopes", "issuedAt", "fingerprint" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "requestedId", "capabilities", "commands", "status", "pairedAt", "tokens", "metadata" ], "additionalProperties": true } }, "required": [ "peer" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:remote" ], "parameters": [ { "name": "peerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "peerId": { "type": "string" }, "note": { "type": "string" }, "requeueClaimedWork": { "type": "boolean" } }, "required": [ "peerId" ], "additionalProperties": true } } } } } }, "/api/remote/peers/{peerId}/invoke": { "post": { "operationId": "remote.peers.invoke", "summary": "Invoke Remote Peer", "description": "Invoke a method on a connected remote peer.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "work": { "type": "object", "properties": { "id": { "type": "string" }, "peerId": { "type": "string" }, "peerKind": { "type": "string", "enum": [ "node", "device" ] }, "type": { "type": "string", "enum": [ "invoke", "status.request", "location.request", "session.message", "automation.run", "device.capability" ] }, "command": { "type": "string" }, "priority": { "type": "string", "enum": [ "default", "normal", "high" ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "completed", "failed", "cancelled", "expired" ] }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "queuedBy": { "type": "string" }, "claimedAt": { "type": "number" }, "claimTokenId": { "type": "string" }, "leaseExpiresAt": { "type": "number" }, "completedAt": { "type": "number" }, "timeoutMs": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "automationRunId": { "type": "string" }, "automationJobId": { "type": "string" }, "approvalId": { "type": "string" }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "peerId", "peerKind", "type", "command", "priority", "status", "createdAt", "updatedAt", "queuedBy", "metadata" ], "additionalProperties": true }, "completed": { "type": "boolean" } }, "required": [ "work", "completed" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:remote" ], "parameters": [ { "name": "peerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "peerId": { "type": "string" }, "command": { "type": "string" }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "priority": { "type": "string", "enum": [ "default", "normal", "high" ] }, "waitMs": { "type": "number" }, "timeoutMs": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "automationRunId": { "type": "string" }, "automationJobId": { "type": "string" }, "approvalId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "peerId", "command" ], "additionalProperties": true } } } } } }, "/api/remote/peers": { "get": { "operationId": "remote.peers.list", "summary": "List Remote Peers", "description": "Return known remote peers.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "peers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "node", "device" ] }, "label": { "type": "string" }, "requestedId": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "object", "additionalProperties": { "type": "boolean" } }, "status": { "type": "string", "enum": [ "paired", "connected", "idle", "disconnected", "revoked" ] }, "pairedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "lastConnectedAt": { "type": "number" }, "lastDisconnectedAt": { "type": "number" }, "lastRemoteAddress": { "type": "string" }, "activeTokenId": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "issuedAt": { "type": "number" }, "lastUsedAt": { "type": "number" }, "rotatedAt": { "type": "number" }, "revokedAt": { "type": "number" }, "fingerprint": { "type": "string" } }, "required": [ "id", "label", "scopes", "issuedAt", "fingerprint" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "requestedId", "capabilities", "commands", "status", "pairedAt", "tokens", "metadata" ], "additionalProperties": true } } }, "required": [ "peers" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:remote" ] } }, "/api/remote/peers/{peerId}/token/revoke": { "post": { "operationId": "remote.peers.token.revoke", "summary": "Revoke Remote Peer Token", "description": "Revoke the active token for a remote peer.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "peer": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "node", "device" ] }, "label": { "type": "string" }, "requestedId": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "object", "additionalProperties": { "type": "boolean" } }, "status": { "type": "string", "enum": [ "paired", "connected", "idle", "disconnected", "revoked" ] }, "pairedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "lastConnectedAt": { "type": "number" }, "lastDisconnectedAt": { "type": "number" }, "lastRemoteAddress": { "type": "string" }, "activeTokenId": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "issuedAt": { "type": "number" }, "lastUsedAt": { "type": "number" }, "rotatedAt": { "type": "number" }, "revokedAt": { "type": "number" }, "fingerprint": { "type": "string" } }, "required": [ "id", "label", "scopes", "issuedAt", "fingerprint" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "requestedId", "capabilities", "commands", "status", "pairedAt", "tokens", "metadata" ], "additionalProperties": true } }, "required": [ "peer" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:remote" ], "parameters": [ { "name": "peerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "peerId": { "type": "string" }, "tokenId": { "type": "string" }, "note": { "type": "string" } }, "required": [ "peerId" ], "additionalProperties": true } } } } } }, "/api/remote/peers/{peerId}/token/rotate": { "post": { "operationId": "remote.peers.token.rotate", "summary": "Rotate Remote Peer Token", "description": "Rotate the active token for a remote peer.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "peer": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "node", "device" ] }, "label": { "type": "string" }, "requestedId": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "object", "additionalProperties": { "type": "boolean" } }, "status": { "type": "string", "enum": [ "paired", "connected", "idle", "disconnected", "revoked" ] }, "pairedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "lastConnectedAt": { "type": "number" }, "lastDisconnectedAt": { "type": "number" }, "lastRemoteAddress": { "type": "string" }, "activeTokenId": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "issuedAt": { "type": "number" }, "lastUsedAt": { "type": "number" }, "rotatedAt": { "type": "number" }, "revokedAt": { "type": "number" }, "fingerprint": { "type": "string" } }, "required": [ "id", "label", "scopes", "issuedAt", "fingerprint" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "requestedId", "capabilities", "commands", "status", "pairedAt", "tokens", "metadata" ], "additionalProperties": true }, "token": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "issuedAt": { "type": "number" }, "lastUsedAt": { "type": "number" }, "rotatedAt": { "type": "number" }, "revokedAt": { "type": "number" }, "fingerprint": { "type": "string" }, "value": { "type": "string" } }, "required": [ "id", "label", "scopes", "issuedAt", "fingerprint", "value" ], "additionalProperties": true } }, "required": [ "peer", "token" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:remote" ], "parameters": [ { "name": "peerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "peerId": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "peerId" ], "additionalProperties": true } } } } } }, "/api/remote": { "get": { "operationId": "remote.snapshot", "summary": "Remote Runtime Snapshot", "description": "Return distributed node/device runtime state.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "daemon": { "type": "object", "properties": { "transportState": { "type": "string" }, "isRunning": { "type": "boolean" }, "reconnectAttempts": { "type": "number" }, "runningJobCount": { "type": "number" }, "lastError": { "type": "string" } }, "required": [ "transportState", "isRunning", "reconnectAttempts", "runningJobCount" ], "additionalProperties": true }, "acp": { "type": "object", "properties": { "transportState": { "type": "string" }, "activeConnectionIds": { "type": "array", "items": { "type": "string" } }, "totalSpawned": { "type": "number" }, "totalFailed": { "type": "number" }, "lastError": { "type": "string" } }, "required": [ "transportState", "activeConnectionIds", "totalSpawned", "totalFailed" ], "additionalProperties": true }, "registry": { "type": "object", "properties": { "pools": { "type": "number" }, "contracts": { "type": "number" }, "artifacts": { "type": "number" }, "poolEntries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "trustClass": { "type": "string" }, "preferredTemplate": { "type": "string" }, "maxRunners": { "type": "number" }, "runnerIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "trustClass", "preferredTemplate", "maxRunners", "runnerIds" ], "additionalProperties": true } }, "contractEntries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runnerId": { "type": "string" }, "label": { "type": "string" }, "template": { "type": "string" }, "poolId": { "type": "string" }, "taskId": { "type": "string" }, "sourceTransport": { "type": "string" }, "trustClass": { "type": "string" }, "executionProtocol": { "type": "string" }, "reviewMode": { "type": "string" }, "communicationLane": { "type": "string" }, "transportState": { "type": "string" }, "lastError": { "type": "string" } }, "required": [ "id", "runnerId", "label", "template", "sourceTransport", "trustClass", "executionProtocol", "reviewMode", "communicationLane", "transportState" ], "additionalProperties": true } }, "artifactEntries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runnerId": { "type": "string" }, "createdAt": { "type": "number" }, "status": { "type": "string" }, "summary": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "runnerId", "createdAt", "status", "summary" ], "additionalProperties": true } } }, "required": [ "pools", "contracts", "artifacts", "poolEntries", "contractEntries", "artifactEntries" ], "additionalProperties": false }, "supervisor": { "type": "object", "properties": { "sessions": { "type": "number" }, "degraded": { "type": "number" }, "capturedAt": { "type": "number" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "runnerId": { "type": "string" }, "label": { "type": "string" }, "transportState": { "type": "string" }, "heartbeat": { "type": "string" }, "taskId": { "type": "string" } }, "required": [ "runnerId", "label", "transportState", "heartbeat" ], "additionalProperties": true } } }, "required": [ "sessions", "degraded", "capturedAt", "entries" ], "additionalProperties": false }, "distributed": { "type": "object", "properties": { "pairRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "peerKind": { "type": "string", "enum": [ "node", "device" ] }, "requestedId": { "type": "string" }, "label": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "requestedBy": { "type": "string", "enum": [ "remote", "operator" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "verified", "rejected", "expired" ] }, "challengePreview": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "approvedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "rejectedAt": { "type": "number" }, "expiresAt": { "type": "number" }, "peerId": { "type": "string" }, "remoteAddress": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "peerKind", "requestedId", "label", "capabilities", "commands", "requestedBy", "status", "challengePreview", "createdAt", "updatedAt", "expiresAt", "metadata" ], "additionalProperties": true } }, "peers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "node", "device" ] }, "label": { "type": "string" }, "requestedId": { "type": "string" }, "platform": { "type": "string" }, "deviceFamily": { "type": "string" }, "version": { "type": "string" }, "clientMode": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "object", "additionalProperties": { "type": "boolean" } }, "status": { "type": "string", "enum": [ "paired", "connected", "idle", "disconnected", "revoked" ] }, "pairedAt": { "type": "number" }, "verifiedAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "lastConnectedAt": { "type": "number" }, "lastDisconnectedAt": { "type": "number" }, "lastRemoteAddress": { "type": "string" }, "activeTokenId": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "issuedAt": { "type": "number" }, "lastUsedAt": { "type": "number" }, "rotatedAt": { "type": "number" }, "revokedAt": { "type": "number" }, "fingerprint": { "type": "string" } }, "required": [ "id", "label", "scopes", "issuedAt", "fingerprint" ], "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "requestedId", "capabilities", "commands", "status", "pairedAt", "tokens", "metadata" ], "additionalProperties": true } }, "work": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "peerId": { "type": "string" }, "peerKind": { "type": "string", "enum": [ "node", "device" ] }, "type": { "type": "string", "enum": [ "invoke", "status.request", "location.request", "session.message", "automation.run", "device.capability" ] }, "command": { "type": "string" }, "priority": { "type": "string", "enum": [ "default", "normal", "high" ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "completed", "failed", "cancelled", "expired" ] }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "queuedBy": { "type": "string" }, "claimedAt": { "type": "number" }, "claimTokenId": { "type": "string" }, "leaseExpiresAt": { "type": "number" }, "completedAt": { "type": "number" }, "timeoutMs": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "automationRunId": { "type": "string" }, "automationJobId": { "type": "string" }, "approvalId": { "type": "string" }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "peerId", "peerKind", "type", "command", "priority", "status", "createdAt", "updatedAt", "queuedBy", "metadata" ], "additionalProperties": true } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "enum": [ "pair-requested", "pair-approved", "pair-rejected", "pair-verified", "pair-expired", "token-rotated", "token-revoked", "peer-connected", "peer-disconnected", "work-queued", "work-claimed", "work-completed", "work-failed", "work-cancelled", "work-expired" ] }, "actor": { "type": "string" }, "peerId": { "type": "string" }, "requestId": { "type": "string" }, "workId": { "type": "string" }, "createdAt": { "type": "number" }, "note": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "action", "actor", "createdAt", "metadata" ], "additionalProperties": true } } }, "required": [ "pairRequests", "peers", "work", "audit" ], "additionalProperties": false } }, "required": [ "daemon", "acp", "registry", "supervisor", "distributed" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:remote" ] } }, "/api/remote/work/{workId}/cancel": { "post": { "operationId": "remote.work.cancel", "summary": "Cancel Remote Work", "description": "Cancel a remote work item.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "work": { "type": "object", "properties": { "id": { "type": "string" }, "peerId": { "type": "string" }, "peerKind": { "type": "string", "enum": [ "node", "device" ] }, "type": { "type": "string", "enum": [ "invoke", "status.request", "location.request", "session.message", "automation.run", "device.capability" ] }, "command": { "type": "string" }, "priority": { "type": "string", "enum": [ "default", "normal", "high" ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "completed", "failed", "cancelled", "expired" ] }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "queuedBy": { "type": "string" }, "claimedAt": { "type": "number" }, "claimTokenId": { "type": "string" }, "leaseExpiresAt": { "type": "number" }, "completedAt": { "type": "number" }, "timeoutMs": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "automationRunId": { "type": "string" }, "automationJobId": { "type": "string" }, "approvalId": { "type": "string" }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "peerId", "peerKind", "type", "command", "priority", "status", "createdAt", "updatedAt", "queuedBy", "metadata" ], "additionalProperties": true } }, "required": [ "work" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:remote" ], "parameters": [ { "name": "workId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workId": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "workId" ], "additionalProperties": true } } } } } }, "/api/remote/work": { "get": { "operationId": "remote.work.list", "summary": "List Remote Work", "description": "Return queued and leased remote work items.", "tags": [ "remote" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "work": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "peerId": { "type": "string" }, "peerKind": { "type": "string", "enum": [ "node", "device" ] }, "type": { "type": "string", "enum": [ "invoke", "status.request", "location.request", "session.message", "automation.run", "device.capability" ] }, "command": { "type": "string" }, "priority": { "type": "string", "enum": [ "default", "normal", "high" ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "completed", "failed", "cancelled", "expired" ] }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "queuedBy": { "type": "string" }, "claimedAt": { "type": "number" }, "claimTokenId": { "type": "string" }, "leaseExpiresAt": { "type": "number" }, "completedAt": { "type": "number" }, "timeoutMs": { "type": "number" }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "automationRunId": { "type": "string" }, "automationJobId": { "type": "string" }, "approvalId": { "type": "string" }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "error": { "type": "string" }, "telemetry": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "reasoningTokens": { "type": "number" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false }, "llmCallCount": { "type": "number" }, "toolCallCount": { "type": "number" }, "turnCount": { "type": "number" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "reasoningSummaryPresent": { "type": "boolean" }, "source": { "type": "string", "enum": [ "local-agent", "shared-session", "remote-node", "remote-device" ] } }, "required": [ "usage" ], "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "peerId", "peerKind", "type", "command", "priority", "status", "createdAt", "updatedAt", "queuedBy", "metadata" ], "additionalProperties": true } } }, "required": [ "work" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:remote" ] } }, "/api/review": { "get": { "operationId": "review.snapshot", "summary": "Review Snapshot", "description": "Return the integration review snapshot used by external helpers.", "tags": [ "review" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiFamilies": { "type": "array", "items": { "type": "string" } }, "routes": { "type": "array", "items": { "type": "string" } }, "sessions": { "type": "number" }, "tasks": { "type": "number" }, "pendingApprovals": { "type": "number" }, "remoteContracts": { "type": "number" }, "panels": { "type": "number" } }, "required": [ "apiFamilies", "routes", "sessions", "tasks", "pendingApprovals", "remoteContracts", "panels" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:automation" ] } }, "/api/routes/bindings": { "post": { "operationId": "routes.bindings.create", "summary": "Create Route Binding", "description": "Create or upsert a route binding.", "tags": [ "routes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:routes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string" }, "threadPolicy": { "type": "string" }, "deliveryGuarantee": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "kind", "surfaceKind", "surfaceId", "externalId" ], "additionalProperties": true } } } } }, "get": { "operationId": "routes.bindings.list", "summary": "List Route Bindings", "description": "Return configured route bindings.", "tags": [ "routes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bindings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true } } }, "required": [ "bindings" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:routes" ] } }, "/api/routes/bindings/{bindingId}": { "delete": { "operationId": "routes.bindings.delete", "summary": "Delete Route Binding", "description": "Delete an existing route binding.", "tags": [ "routes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "removed" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:routes" ], "x-dangerous": true, "parameters": [ { "name": "bindingId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "routes.bindings.update", "summary": "Update Route Binding", "description": "Update an existing route binding. (Renamed from routes.bindings.patch in the 1.0.0 core-verb rename, canonical verb is update, not patch.)", "tags": [ "routes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:routes" ], "parameters": [ { "name": "bindingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bindingId": { "type": "string" }, "sessionPolicy": { "type": "string" }, "threadPolicy": { "type": "string" }, "deliveryGuarantee": { "type": "string" }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/routes": { "get": { "operationId": "routes.snapshot", "summary": "Route Snapshot", "description": "Return the route and binding integration snapshot.", "tags": [ "routes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalBindings": { "type": "number" }, "activeBindings": { "type": "number" }, "recentBindings": { "type": "number" }, "bindings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "session", "thread", "channel", "message" ] }, "surfaceKind": { "type": "string", "enum": [ "tui", "web", "slack", "discord", "ntfy", "webhook", "homeassistant", "telegram", "google-chat", "signal", "whatsapp", "telephony", "imessage", "msteams", "bluebubbles", "mattermost", "matrix", "service" ] }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "sessionPolicy": { "type": "string", "enum": [ "create-or-bind", "continue-existing", "require-existing" ] }, "threadPolicy": { "type": "string", "enum": [ "preserve", "replace", "detached" ] }, "deliveryGuarantee": { "type": "string", "enum": [ "best-effort", "at-least-once" ] }, "threadId": { "type": "string" }, "channelId": { "type": "string" }, "sessionId": { "type": "string" }, "jobId": { "type": "string" }, "runId": { "type": "string" }, "title": { "type": "string" }, "lastSeenAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "surfaceKind", "surfaceId", "externalId", "lastSeenAt", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true } } }, "required": [ "totalBindings", "activeBindings", "recentBindings", "bindings" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:routes" ] } }, "/api/surfaces": { "get": { "operationId": "surfaces.list", "summary": "List Surfaces", "description": "Return registered channel and control surfaces.", "tags": [ "routes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "surfaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "state": { "type": "string" }, "configuredAt": { "type": "number" }, "lastSeenAt": { "type": "number" }, "defaultRouteId": { "type": "string" }, "accountId": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "state", "configuredAt", "capabilities", "metadata" ], "additionalProperties": false } } }, "required": [ "surfaces" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:routes" ] } }, "/api/devices/artifacts": { "get": { "operationId": "devices.artifacts.list", "summary": "List Retained Device Captures", "description": "The camera and screen captures still inside their retention window, newest first, with when each was captured, when it will be deleted, and the reason the request stated. Expired captures are never listed, retention is enforced by the store, not by this verb filtering them out of a longer list.", "tags": [ "runtime" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "type": "object", "properties": { "artifactId": { "type": "string" }, "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "kind": { "type": "string" }, "mediaType": { "type": "string" }, "byteLength": { "type": "number" }, "capturedAt": { "type": "number" }, "expiresAt": { "type": "number" }, "reason": { "type": "string" }, "daemonPath": { "type": "string" } }, "required": [ "artifactId", "nodeId", "capabilityId", "kind", "mediaType", "byteLength", "capturedAt", "expiresAt", "reason", "daemonPath" ], "additionalProperties": false } }, "retained": { "type": "number" }, "retentionHours": { "type": "number" } }, "required": [ "artifacts", "retained", "retentionHours" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:remote" ], "parameters": [ { "name": "nodeId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/devices/artifacts/{artifactId}": { "get": { "operationId": "devices.artifacts.read", "summary": "Read a Retained Device Capture", "description": "Return one retained capture's bytes, base64-encoded, for a caller that is not running on the daemon host and so cannot open the file itself. The store re-hashes the bytes against the digest recorded when the capture was retained and refuses to serve a mismatch, so a torn or half-written file is never handed back as if it were the picture that was taken. A capture that is gone, expired, swept, missing, or corrupted, is an honest 404 naming which of those it was.", "tags": [ "runtime" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact": { "type": "object", "properties": { "artifactId": { "type": "string" }, "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "kind": { "type": "string" }, "mediaType": { "type": "string" }, "byteLength": { "type": "number" }, "capturedAt": { "type": "number" }, "expiresAt": { "type": "number" }, "reason": { "type": "string" }, "daemonPath": { "type": "string" } }, "required": [ "artifactId", "nodeId", "capabilityId", "kind", "mediaType", "byteLength", "capturedAt", "expiresAt", "reason", "daemonPath" ], "additionalProperties": false }, "dataBase64": { "type": "string" } }, "required": [ "artifact", "dataBase64" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:remote" ], "parameters": [ { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/devices/capability/request": { "post": { "operationId": "devices.capability.request", "summary": "Request a Capability From a Paired Device", "description": "Ask one paired device node for one capability, a photo, a screen capture, a location fix, its clipboard, a notification, a link to open, a buzz, and return what came back. The reason is required and is shown VERBATIM on the confirmation prompt, so the person deciding sees what the caller said it was for. Every gate lives in the daemon-owned device runtime and this verb re-decides none of them: a durable grant is re-read from disk (never cached), a request with no grant asks the person on whatever surface they are looking at, a capability turned off by configuration is refused with the configuration key that turned it off, and a capture is retained under the configured retention window and disclosed. A refusal is returned as ok:false with the reason and a machine-readable refusal code, it is an answer, not an error. A capability that produces a capture returns an artifact REFERENCE; fetch the bytes with devices.artifacts.read.", "tags": [ "runtime" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "capabilityTitle": { "type": "string" }, "authority": { "type": "string" }, "grantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "anyOf": [ { "type": "object", "properties": { "artifactId": { "type": "string" }, "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "kind": { "type": "string" }, "mediaType": { "type": "string" }, "byteLength": { "type": "number" }, "capturedAt": { "type": "number" }, "expiresAt": { "type": "number" }, "reason": { "type": "string" }, "daemonPath": { "type": "string" } }, "required": [ "artifactId", "nodeId", "capabilityId", "kind", "mediaType", "byteLength", "capturedAt", "expiresAt", "reason", "daemonPath" ], "additionalProperties": false }, { "type": "null" } ] }, "refusal": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "ok", "nodeId", "capabilityId", "capabilityTitle", "authority", "grantId", "artifact", "refusal", "detail" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:remote" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "reason": { "type": "string" }, "input": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } }, "sessionId": { "type": "string" }, "timeoutMs": { "type": "number" } }, "required": [ "nodeId", "capabilityId", "reason" ], "additionalProperties": false } } } } } }, "/api/devices/grants": { "get": { "operationId": "devices.grants.list", "summary": "List Device Capability Grants", "description": "The durable \"always allow\" grants a person gave, per capability and per device, with when each was granted, when it expires, and how often it has been used, plus the recent ledger of grants given, used, revoked, and expired.", "tags": [ "runtime" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "grants": { "type": "array", "items": { "type": "object", "properties": { "grantId": { "type": "string" }, "nodeId": { "type": "string" }, "nodeKind": { "type": "string" }, "capabilityId": { "type": "string" }, "capabilityTitle": { "type": "string" }, "scope": { "type": "string" }, "grantedAt": { "type": "number" }, "expiresAt": { "type": "number" }, "lastUsedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "useCount": { "type": "number" }, "grantedBy": { "type": "string" } }, "required": [ "grantId", "nodeId", "nodeKind", "capabilityId", "capabilityTitle", "scope", "grantedAt", "expiresAt", "lastUsedAt", "useCount", "grantedBy" ], "additionalProperties": false } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string" }, "grantId": { "type": "string" }, "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "at": { "type": "number" }, "actor": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "action", "grantId", "nodeId", "capabilityId", "at", "actor", "reason" ], "additionalProperties": false } } }, "required": [ "grants", "audit" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:remote" ], "parameters": [ { "name": "nodeId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/devices/grants/revoke": { "post": { "operationId": "devices.grants.revoke", "summary": "Revoke a Device Capability Grant", "description": "Delete durable grants by grant id, by device, by capability, or any combination. Revoked grants are removed rather than flagged, so the next request for that capability asks the person again. Returns exactly what was removed.", "tags": [ "runtime" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "number" }, "removals": { "type": "array", "items": { "type": "object", "properties": { "grantId": { "type": "string" }, "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "scope": { "type": "string" }, "reason": { "type": "string" }, "removedAt": { "type": "number" } }, "required": [ "grantId", "nodeId", "capabilityId", "scope", "reason", "removedAt" ], "additionalProperties": false } } }, "required": [ "revoked", "removals" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:config" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grantId": { "type": "string" }, "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": false } } } } } }, "/api/devices/housekeeping": { "post": { "operationId": "devices.housekeeping.run", "summary": "Run Device Housekeeping", "description": "Sweep the device grants ledger and the retained captures now: expired and orphaned grants removed, captures past their retention window deleted, torn or missing capture files reaped. Returns the itemised disclosure of everything removed and why.", "tags": [ "runtime" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "sweptAt": { "type": "number" }, "grantsRemoved": { "type": "array", "items": { "type": "object", "properties": { "grantId": { "type": "string" }, "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "scope": { "type": "string" }, "reason": { "type": "string" }, "removedAt": { "type": "number" } }, "required": [ "grantId", "nodeId", "capabilityId", "scope", "reason", "removedAt" ], "additionalProperties": false } }, "grantsRetained": { "type": "number" }, "capturesRemoved": { "type": "array", "items": { "type": "object", "properties": { "artifactId": { "type": "string" }, "nodeId": { "type": "string" }, "capabilityId": { "type": "string" }, "fileName": { "type": "string" }, "reason": { "type": "string" }, "removedAt": { "type": "number" }, "byteLength": { "type": "number" } }, "required": [ "artifactId", "nodeId", "capabilityId", "fileName", "reason", "removedAt", "byteLength" ], "additionalProperties": false } }, "capturesRetained": { "type": "number" }, "bytesReclaimed": { "type": "number" } }, "required": [ "summary", "sweptAt", "grantsRemoved", "grantsRetained", "capturesRemoved", "capturesRetained", "bytesReclaimed" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:config" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/devices/nodes": { "get": { "operationId": "devices.nodes.list", "summary": "List Paired Device Nodes", "description": "Every phone paired as a device node, with the capabilities it announced, the ones it did not offer, and the ones it announced but cannot currently serve because its connection is not a secure context. Node-kind neutral: a web app node and a native app node are described identically.", "tags": [ "runtime" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string" }, "nodeKind": { "type": "string" }, "nodeKindLabel": { "type": "string" }, "label": { "type": "string" }, "platform": { "type": "string" }, "appVersion": { "type": "string" }, "contractVersion": { "type": "number" }, "contractCompatible": { "type": "boolean" }, "supported": { "type": "array", "items": { "type": "string" } }, "undeclared": { "type": "array", "items": { "type": "string" } }, "gatedBySecureContext": { "type": "array", "items": { "type": "string" } }, "unknownDeclared": { "type": "array", "items": { "type": "string" } } }, "required": [ "nodeId", "nodeKind", "nodeKindLabel", "label", "platform", "appVersion", "contractVersion", "contractCompatible", "supported", "undeclared", "gatedBySecureContext", "unknownDeclared" ], "additionalProperties": false } }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "family": { "type": "string" }, "title": { "type": "string" }, "purpose": { "type": "string" }, "effect": { "type": "string" }, "sensitivity": { "type": "string" }, "producesArtifact": { "type": "boolean" }, "allowAlwaysOffered": { "type": "boolean" } }, "required": [ "id", "family", "title", "purpose", "effect", "sensitivity", "producesArtifact", "allowAlwaysOffered" ], "additionalProperties": false } }, "mode": { "type": "string" }, "allowAlwaysOffer": { "type": "string" }, "captureRetentionHours": { "type": "number" } }, "required": [ "nodes", "capabilities", "mode", "allowAlwaysOffer", "captureRetentionHours" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:remote" ] } }, "/api/runtime/metrics": { "get": { "operationId": "runtime.metrics.get", "summary": "Runtime Metrics", "description": "Return the process-wide runtime metrics snapshot: HTTP/LLM/auth/transport counters, gauges, request-duration and token histograms, and per-model tool-format telemetry (edit-tool failure classes and declared exec-expectation misses).", "tags": [ "runtime" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "counters": { "type": "object", "properties": {}, "additionalProperties": true }, "gauges": { "type": "object", "properties": {}, "additionalProperties": true }, "histograms": { "type": "object", "properties": {}, "additionalProperties": true }, "toolFormat": { "type": "object", "properties": { "byModel": { "type": "object", "properties": {}, "additionalProperties": true }, "byClass": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "byModel", "byClass" ], "additionalProperties": false } }, "required": [ "counters", "gauges", "histograms", "toolFormat" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:telemetry" ] } }, "/api/runtime/scheduler": { "get": { "operationId": "scheduler.capacity", "summary": "Scheduler Capacity", "description": "Return the current automation-scheduler capacity snapshot: total slots, in-use slots, queue depth, and age of the oldest queued run.", "tags": [ "scheduler" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "slotsTotal": { "type": "number" }, "slotsInUse": { "type": "number" }, "queueDepth": { "type": "number" }, "oldestQueuedAgeMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "slotsTotal", "slotsInUse", "queueDepth", "oldestQueuedAgeMs" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:automation" ] } }, "/api/service/install": { "post": { "operationId": "services.install", "summary": "Install Service", "description": "Install the GoodVibes platform service.", "tags": [ "services" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "serviceName": { "type": "string" }, "path": { "type": "string" }, "installed": { "type": "boolean" }, "autostart": { "type": "boolean" }, "running": { "type": "boolean" }, "pid": { "type": "number" }, "logPath": { "type": "string" }, "commandPreview": { "type": "string" }, "contents": { "type": "string" }, "suggestedCommands": { "type": "array", "items": { "type": "string" } }, "lastAction": { "type": "string" }, "actionError": { "type": "string" }, "network": { "type": "object", "properties": { "controlPlane": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "httpListener": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "outbound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "bundled", "bundled+custom", "custom" ] }, "allowInsecureLocalhost": { "type": "boolean" }, "customCaFile": { "type": "string" }, "customCaDir": { "type": "string" }, "customCaEntryCount": { "type": "number" }, "effectiveCaStrategy": { "type": "string", "enum": [ "bun-default", "bundled+custom", "custom" ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowInsecureLocalhost", "customCaEntryCount", "effectiveCaStrategy", "errors" ], "additionalProperties": false } }, "required": [ "controlPlane", "httpListener", "outbound" ], "additionalProperties": false } }, "required": [ "platform", "serviceName", "path", "installed", "autostart", "running", "commandPreview", "suggestedCommands" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/service/restart": { "post": { "operationId": "services.restart", "summary": "Restart Service", "description": "Restart the GoodVibes platform service.", "tags": [ "services" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "serviceName": { "type": "string" }, "path": { "type": "string" }, "installed": { "type": "boolean" }, "autostart": { "type": "boolean" }, "running": { "type": "boolean" }, "pid": { "type": "number" }, "logPath": { "type": "string" }, "commandPreview": { "type": "string" }, "contents": { "type": "string" }, "suggestedCommands": { "type": "array", "items": { "type": "string" } }, "lastAction": { "type": "string" }, "actionError": { "type": "string" }, "network": { "type": "object", "properties": { "controlPlane": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "httpListener": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "outbound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "bundled", "bundled+custom", "custom" ] }, "allowInsecureLocalhost": { "type": "boolean" }, "customCaFile": { "type": "string" }, "customCaDir": { "type": "string" }, "customCaEntryCount": { "type": "number" }, "effectiveCaStrategy": { "type": "string", "enum": [ "bun-default", "bundled+custom", "custom" ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowInsecureLocalhost", "customCaEntryCount", "effectiveCaStrategy", "errors" ], "additionalProperties": false } }, "required": [ "controlPlane", "httpListener", "outbound" ], "additionalProperties": false } }, "required": [ "platform", "serviceName", "path", "installed", "autostart", "running", "commandPreview", "suggestedCommands" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/service/start": { "post": { "operationId": "services.start", "summary": "Start Service", "description": "Start the GoodVibes platform service.", "tags": [ "services" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "serviceName": { "type": "string" }, "path": { "type": "string" }, "installed": { "type": "boolean" }, "autostart": { "type": "boolean" }, "running": { "type": "boolean" }, "pid": { "type": "number" }, "logPath": { "type": "string" }, "commandPreview": { "type": "string" }, "contents": { "type": "string" }, "suggestedCommands": { "type": "array", "items": { "type": "string" } }, "lastAction": { "type": "string" }, "actionError": { "type": "string" }, "network": { "type": "object", "properties": { "controlPlane": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "httpListener": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "outbound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "bundled", "bundled+custom", "custom" ] }, "allowInsecureLocalhost": { "type": "boolean" }, "customCaFile": { "type": "string" }, "customCaDir": { "type": "string" }, "customCaEntryCount": { "type": "number" }, "effectiveCaStrategy": { "type": "string", "enum": [ "bun-default", "bundled+custom", "custom" ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowInsecureLocalhost", "customCaEntryCount", "effectiveCaStrategy", "errors" ], "additionalProperties": false } }, "required": [ "controlPlane", "httpListener", "outbound" ], "additionalProperties": false } }, "required": [ "platform", "serviceName", "path", "installed", "autostart", "running", "commandPreview", "suggestedCommands" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/service/status": { "get": { "operationId": "services.status", "summary": "Service Status", "description": "Return platform service installation and runtime posture.", "tags": [ "services" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "serviceName": { "type": "string" }, "path": { "type": "string" }, "installed": { "type": "boolean" }, "autostart": { "type": "boolean" }, "running": { "type": "boolean" }, "pid": { "type": "number" }, "logPath": { "type": "string" }, "commandPreview": { "type": "string" }, "contents": { "type": "string" }, "suggestedCommands": { "type": "array", "items": { "type": "string" } }, "lastAction": { "type": "string" }, "actionError": { "type": "string" }, "network": { "type": "object", "properties": { "controlPlane": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "httpListener": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "outbound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "bundled", "bundled+custom", "custom" ] }, "allowInsecureLocalhost": { "type": "boolean" }, "customCaFile": { "type": "string" }, "customCaDir": { "type": "string" }, "customCaEntryCount": { "type": "number" }, "effectiveCaStrategy": { "type": "string", "enum": [ "bun-default", "bundled+custom", "custom" ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowInsecureLocalhost", "customCaEntryCount", "effectiveCaStrategy", "errors" ], "additionalProperties": false } }, "required": [ "controlPlane", "httpListener", "outbound" ], "additionalProperties": false } }, "required": [ "platform", "serviceName", "path", "installed", "autostart", "running", "commandPreview", "suggestedCommands" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:services" ] } }, "/api/service/stop": { "post": { "operationId": "services.stop", "summary": "Stop Service", "description": "Stop the GoodVibes platform service.", "tags": [ "services" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "serviceName": { "type": "string" }, "path": { "type": "string" }, "installed": { "type": "boolean" }, "autostart": { "type": "boolean" }, "running": { "type": "boolean" }, "pid": { "type": "number" }, "logPath": { "type": "string" }, "commandPreview": { "type": "string" }, "contents": { "type": "string" }, "suggestedCommands": { "type": "array", "items": { "type": "string" } }, "lastAction": { "type": "string" }, "actionError": { "type": "string" }, "network": { "type": "object", "properties": { "controlPlane": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "httpListener": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "outbound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "bundled", "bundled+custom", "custom" ] }, "allowInsecureLocalhost": { "type": "boolean" }, "customCaFile": { "type": "string" }, "customCaDir": { "type": "string" }, "customCaEntryCount": { "type": "number" }, "effectiveCaStrategy": { "type": "string", "enum": [ "bun-default", "bundled+custom", "custom" ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowInsecureLocalhost", "customCaEntryCount", "effectiveCaStrategy", "errors" ], "additionalProperties": false } }, "required": [ "controlPlane", "httpListener", "outbound" ], "additionalProperties": false } }, "required": [ "platform", "serviceName", "path", "installed", "autostart", "running", "commandPreview", "suggestedCommands" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/service/uninstall": { "post": { "operationId": "services.uninstall", "summary": "Uninstall Service", "description": "Uninstall the GoodVibes platform service.", "tags": [ "services" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "serviceName": { "type": "string" }, "path": { "type": "string" }, "installed": { "type": "boolean" }, "autostart": { "type": "boolean" }, "running": { "type": "boolean" }, "pid": { "type": "number" }, "logPath": { "type": "string" }, "commandPreview": { "type": "string" }, "contents": { "type": "string" }, "suggestedCommands": { "type": "array", "items": { "type": "string" } }, "lastAction": { "type": "string" }, "actionError": { "type": "string" }, "network": { "type": "object", "properties": { "controlPlane": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "httpListener": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "controlPlane", "httpListener" ] }, "host": { "type": "string" }, "port": { "type": "number" }, "mode": { "type": "string", "enum": [ "off", "proxy", "direct" ] }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "trustProxy": { "type": "boolean" }, "certFile": { "type": "string" }, "keyFile": { "type": "string" }, "usingDefaultPaths": { "type": "boolean" }, "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "keyPermissions": { "type": "object", "properties": { "available": { "type": "boolean" }, "safe": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "available" ], "additionalProperties": false } }, "required": [ "surface", "host", "port", "mode", "scheme", "trustProxy", "usingDefaultPaths", "ready", "errors" ], "additionalProperties": false }, "outbound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "bundled", "bundled+custom", "custom" ] }, "allowInsecureLocalhost": { "type": "boolean" }, "customCaFile": { "type": "string" }, "customCaDir": { "type": "string" }, "customCaEntryCount": { "type": "number" }, "effectiveCaStrategy": { "type": "string", "enum": [ "bun-default", "bundled+custom", "custom" ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowInsecureLocalhost", "customCaEntryCount", "effectiveCaStrategy", "errors" ], "additionalProperties": false } }, "required": [ "controlPlane", "httpListener", "outbound" ], "additionalProperties": false } }, "required": [ "platform", "serviceName", "path", "installed", "autostart", "running", "commandPreview", "suggestedCommands" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:services" ], "x-dangerous": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/sessions/{sessionId}/close": { "post": { "operationId": "sessions.close", "summary": "Close Shared Session", "description": "Mark a shared session as closed.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false } }, "required": [ "session" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" } }, "required": [ "sessionId" ], "additionalProperties": false } } } } } }, "/api/sessions/{sessionId}/context-usage": { "get": { "operationId": "sessions.contextUsage.get", "summary": "Get Session Context Usage", "description": "Return the live context-window usage for a session: estimatedContextTokens (the token ESTIMATOR's figure, not a measured provider count), the model contextWindow, and the derived contextUsagePct and contextRemainingTokens. `estimated` is always true, marking the token figure as an estimate rather than a fact. Only the daemon's live local runtime session is resolvable; any other session id is a 404 SESSION_NOT_LOCAL.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "estimatedContextTokens": { "type": "number" }, "contextWindow": { "type": "number" }, "contextUsagePct": { "type": "number" }, "contextRemainingTokens": { "type": "number" }, "estimated": { "type": "boolean" } }, "required": [ "sessionId", "estimatedContextTokens", "contextWindow", "contextUsagePct", "contextRemainingTokens", "estimated" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/sessions": { "post": { "operationId": "sessions.create", "summary": "Create Shared Session", "description": "Create a shared session for a surface, route, or web client.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false } }, "required": [ "session" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" } }, "additionalProperties": true } } } } }, "get": { "operationId": "sessions.list", "summary": "List Shared Sessions", "description": "Return shared-session integration state.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "sessions": { "type": "number" }, "active": { "type": "number" }, "closed": { "type": "number" } }, "required": [ "sessions", "active", "closed" ], "additionalProperties": false }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false } } }, "required": [ "totals", "sessions" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ] } }, "/api/sessions/{sessionId}": { "delete": { "operationId": "sessions.delete", "summary": "Delete Shared Session", "description": "Permanently remove a shared session record and its queued inputs/messages from the home-scoped store. A distinct, explicit hard-delete verb, NEVER triggered by close; closed sessions stay listable (includeClosed) and deletionRetentionMs semantics for non-deleted records are untouched. Requires the session to already be closed: deleting a still-active session is rejected with 409 SESSION_ACTIVE (close it, then delete). An unknown or already-deleted id is a 404 SESSION_NOT_FOUND, never a 200-noop. Emits control.session_update (session-deleted) so subscribers drop the row live.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "sessionId", "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "get": { "operationId": "sessions.get", "summary": "Get Shared Session", "description": "Return metadata for a shared session.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "routeId": { "type": "string" }, "agentId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "sessionId", "role", "body", "createdAt", "metadata" ], "additionalProperties": false } } }, "required": [ "session", "messages" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/sessions/{sessionId}/detach": { "post": { "operationId": "sessions.detach", "summary": "Detach Shared Session Participant", "description": "Remove a surface's participant and its route binding from a session so that surface stops receiving updates, WITHOUT closing or killing the session (detach != close != kill). Every participant carrying the given surfaceId is removed and any route binding they alone held is unbound; the session and all other participants keep running. Idempotent: detaching an already-detached surface, or detaching from a closed session, is a no-op success. An unknown session is a 404.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false } }, "required": [ "session" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "surfaceId": { "type": "string" } }, "required": [ "sessionId", "surfaceId" ], "additionalProperties": false } } } } } }, "/api/sessions/{sessionId}/follow-up": { "post": { "operationId": "sessions.followUp", "summary": "Queue Shared Session Follow-Up", "description": "Queue a deferred follow-up for a shared session so it runs after the current agent completes, or spawn immediately when the session is idle.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false }, { "type": "null" } ] }, "message": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "routeId": { "type": "string" }, "agentId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "sessionId", "role", "body", "createdAt", "metadata" ], "additionalProperties": false }, "input": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "intent": { "type": "string", "enum": [ "submit", "steer", "follow-up" ] }, "state": { "type": "string", "enum": [ "queued", "delivered", "spawned", "completed", "cancelled", "failed", "rejected" ] }, "correlationId": { "type": "string" }, "causationId": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "threadId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "activeAgentId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "error": { "type": "string" } }, "required": [ "id", "sessionId", "intent", "state", "correlationId", "body", "createdAt", "updatedAt", "metadata" ], "additionalProperties": false }, "mode": { "type": "string", "enum": [ "spawn", "continued-live", "queued-follow-up", "queued-for-surface", "rejected" ] }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "session", "message", "input", "mode", "agentId" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false } }, "required": [ "body" ], "additionalProperties": true } } } } } }, "/api/sessions/{sessionId}/inputs/{inputId}/cancel": { "post": { "operationId": "sessions.inputs.cancel", "summary": "Cancel Shared Session Input", "description": "Cancel a queued shared-session input before it is delivered or spawned.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "intent": { "type": "string", "enum": [ "submit", "steer", "follow-up" ] }, "state": { "type": "string", "enum": [ "queued", "delivered", "spawned", "completed", "cancelled", "failed", "rejected" ] }, "correlationId": { "type": "string" }, "causationId": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "threadId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "activeAgentId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "error": { "type": "string" } }, "required": [ "id", "sessionId", "intent", "state", "correlationId", "body", "createdAt", "updatedAt", "metadata" ], "additionalProperties": false } }, "required": [ "input" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "inputId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "inputId": { "type": "string" } }, "required": [ "sessionId", "inputId" ], "additionalProperties": false } } } } } }, "/api/sessions/{sessionId}/inputs/{inputId}/deliver": { "post": { "operationId": "sessions.inputs.deliver", "summary": "Mark Shared Session Input Delivered", "description": "A live registered surface reports that it collected a queued input (moves it to `delivered`) or finished acting on it (`consumed:true` moves it to `completed`). This is how a surface-managed session, where steer/follow-up inputs queue for the surface rather than spawn a daemon executor, closes the input lifecycle honestly. Only queued/delivered inputs advance; others are returned unchanged. `agentId` names the agent the surface is running for this input: it binds the reply so a message that arrived over a channel gets its answer routed back to that conversation, the same binding the daemon makes for the executors it spawns itself. `answer` (sent with `consumed:true`, optionally with `status`) is the output that agent finished with, the daemon writes it into the session and delivers it to the channel.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "intent": { "type": "string", "enum": [ "submit", "steer", "follow-up" ] }, "state": { "type": "string", "enum": [ "queued", "delivered", "spawned", "completed", "cancelled", "failed", "rejected" ] }, "correlationId": { "type": "string" }, "causationId": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "threadId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "activeAgentId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "error": { "type": "string" } }, "required": [ "id", "sessionId", "intent", "state", "correlationId", "body", "createdAt", "updatedAt", "metadata" ], "additionalProperties": false } }, "required": [ "input" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "inputId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "inputId": { "type": "string" }, "consumed": { "type": "boolean" }, "agentId": { "type": "string" }, "answer": { "type": "string" }, "status": { "type": "string" } }, "required": [ "sessionId", "inputId" ], "additionalProperties": false } } } } } }, "/api/sessions/{sessionId}/inputs": { "get": { "operationId": "sessions.inputs.list", "summary": "List Shared Session Inputs", "description": "Return explicit session inputs, including queued follow-ups and delivered steering requests. A live surface collects work by filtering `state` (e.g. queued) and paging past a `since` createdAt cursor (exclusive), draining only inputs it has not yet collected.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "intent": { "type": "string", "enum": [ "submit", "steer", "follow-up" ] }, "state": { "type": "string", "enum": [ "queued", "delivered", "spawned", "completed", "cancelled", "failed", "rejected" ] }, "correlationId": { "type": "string" }, "causationId": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "threadId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "activeAgentId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "error": { "type": "string" } }, "required": [ "id", "sessionId", "intent", "state", "correlationId", "body", "createdAt", "updatedAt", "metadata" ], "additionalProperties": false } } }, "required": [ "session", "inputs" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } } ] } }, "/api/session": { "get": { "operationId": "sessions.integration.snapshot", "summary": "Session Integration Snapshot", "description": "Return the session integration snapshot.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "recoveryState": { "type": "string" }, "projectRoot": { "type": "string" }, "isResumed": { "type": "boolean" }, "resumedFromId": { "type": "string" }, "compactionState": { "type": "string" }, "lastCompactedAt": { "type": "number" }, "lineage": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "title", "status", "recoveryState", "projectRoot", "isResumed", "compactionState", "lineage" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ] } }, "/api/sessions/{sessionId}/messages": { "post": { "operationId": "sessions.messages.create", "summary": "Post Shared Session Message", "description": "Append a user message to a shared session. Omitted `kind` defaults to `message` conversation routing; send `kind: \"task\"` to request agent/WRFC task continuation.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "messageId": { "type": "string" }, "routedTo": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "messageId", "routedTo", "sessionId" ], "additionalProperties": false }, { "type": "object", "properties": { "session": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false }, { "type": "null" } ] }, "message": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "routeId": { "type": "string" }, "agentId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "sessionId", "role", "body", "createdAt", "metadata" ], "additionalProperties": false }, "input": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "intent": { "type": "string", "enum": [ "submit", "steer", "follow-up" ] }, "state": { "type": "string", "enum": [ "queued", "delivered", "spawned", "completed", "cancelled", "failed", "rejected" ] }, "correlationId": { "type": "string" }, "causationId": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "threadId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "activeAgentId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "error": { "type": "string" } }, "required": [ "id", "sessionId", "intent", "state", "correlationId", "body", "createdAt", "updatedAt", "metadata" ], "additionalProperties": false }, "mode": { "type": "string", "enum": [ "spawn", "continued-live", "queued-follow-up", "queued-for-surface", "rejected" ] }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "session", "message", "input", "mode", "agentId" ], "additionalProperties": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "kind": { "type": "string" }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false } }, "required": [ "body" ], "additionalProperties": true } } } } }, "get": { "operationId": "sessions.messages.list", "summary": "List Shared Session Messages", "description": "Return message history for a shared session.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "routeId": { "type": "string" }, "agentId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "sessionId", "role", "body", "createdAt", "metadata" ], "additionalProperties": false } } }, "required": [ "session", "messages" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/sessions/{sessionId}/permission-mode": { "get": { "operationId": "sessions.permissionMode.get", "summary": "Get Session Permission Mode", "description": "Return the permission mode currently in effect for a session (plan/normal/accept-edits/auto, or custom for a bespoke rule set). Only the daemon's live local runtime session is resolvable; any other session id is a 404 SESSION_NOT_LOCAL.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "plan", "normal", "accept-edits", "auto", "custom" ] } }, "required": [ "sessionId", "mode" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "sessions.permissionMode.set", "summary": "Set Session Permission Mode", "description": "Set a session's permission mode to plan, normal, accept-edits, or auto. Emits runtime.permissions (PERMISSION_MODE_CHANGED) so every surface stays in sync. Only the daemon's live local runtime session is settable; any other session id is a 404 SESSION_NOT_LOCAL.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "plan", "normal", "accept-edits", "auto", "custom" ] }, "previousMode": { "type": "string", "enum": [ "plan", "normal", "accept-edits", "auto", "custom" ] } }, "required": [ "sessionId", "mode", "previousMode" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "plan", "normal", "accept-edits", "auto" ] } }, "required": [ "sessionId", "mode" ], "additionalProperties": false } } } } } }, "/api/sessions/{sessionId}/queued-messages/{messageId}": { "delete": { "operationId": "sessions.queuedMessages.delete", "summary": "Delete a Queued Mid-Turn Message", "description": "Remove a message still waiting in the mid-turn queue so it is never delivered. A message already delivered to the model cannot be removed, deleting it is a 404 MESSAGE_NOT_QUEUED. Only the daemon's live local runtime session is controllable; any other session id is a 404 SESSION_NOT_LOCAL.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "sessionId", "id", "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "sessions.queuedMessages.edit", "summary": "Edit a Queued Mid-Turn Message", "description": "Replace the text of a message still waiting in the mid-turn queue. A message already delivered to the model is immutable, editing it is a 404 MESSAGE_NOT_QUEUED. Editing replaces any multimodal content with the new plain text. Only the daemon's live local runtime session is controllable; any other session id is a 404 SESSION_NOT_LOCAL.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "id": { "type": "string" }, "text": { "type": "string" } }, "required": [ "sessionId", "id", "text" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "messageId": { "type": "string" }, "text": { "type": "string" } }, "required": [ "sessionId", "messageId", "text" ], "additionalProperties": false } } } } } }, "/api/sessions/{sessionId}/queued-messages": { "get": { "operationId": "sessions.queuedMessages.list", "summary": "List Queued Mid-Turn Messages", "description": "List the messages queued behind the current turn (submitted while the model was thinking), in delivery order. Queued messages remain editable and deletable until they are delivered; a delivered message no longer appears here. Only the daemon's live local runtime session is resolvable; any other session id is a 404 SESSION_NOT_LOCAL.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "queuedAt": { "type": "number" }, "text": { "type": "string" } }, "required": [ "id", "queuedAt", "text" ], "additionalProperties": false } } }, "required": [ "sessionId", "messages" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/sessions/register": { "post": { "operationId": "sessions.register", "summary": "Register Shared Session", "description": "Idempotently register (or heartbeat) a session keyed on a caller-supplied id, carrying its kind, project, and participant identity. Re-calling with the same id advances the participant lastSeenAt (heartbeat). Registering against a CLOSED session does NOT silently reopen it, the heartbeat is recorded and the still-closed record is returned with reopened=false and conflict={status:closed}; pass reopen=true to reopen. A titled session is never renamed by the heartbeat. An unknown kind is rejected (400), not coerced. Prefer this over sessions.create for external runtimes that own their session id.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false }, "reopened": { "type": "boolean" }, "conflict": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "closed" ] } }, "required": [ "status" ], "additionalProperties": false } }, "required": [ "session", "reopened" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "kind": { "type": "string", "enum": [ "tui", "agent", "webui", "companion-task", "companion-chat", "automation", "channel", "acp", "hosted" ] }, "project": { "type": "string" }, "title": { "type": "string" }, "participant": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false }, "reopen": { "type": "boolean" } }, "required": [ "sessionId", "participant" ], "additionalProperties": true } } } } } }, "/api/sessions/{sessionId}/reopen": { "post": { "operationId": "sessions.reopen", "summary": "Reopen Shared Session", "description": "Reopen a previously closed shared session.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false } }, "required": [ "session" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" } }, "required": [ "sessionId" ], "additionalProperties": false } } } } } }, "/api/sessions/{sessionId}/steer": { "post": { "operationId": "sessions.steer", "summary": "Steer Shared Session", "description": "Deliver a live steering message to the active agent for a shared session, optionally falling back to spawn when explicitly allowed.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "project": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastMessageAt": { "type": "number" }, "closedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "messageCount": { "type": "number" }, "retainedMessageCount": { "type": "number" }, "pendingInputCount": { "type": "number" }, "routeIds": { "type": "array", "items": { "type": "string" } }, "surfaceKinds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "routeId": { "type": "string" }, "lastSeenAt": { "type": "number" } }, "required": [ "surfaceKind", "surfaceId", "lastSeenAt" ], "additionalProperties": false } }, "activeAgentId": { "type": "string" }, "lastAgentId": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "title", "status", "createdAt", "updatedAt", "lastActivityAt", "messageCount", "pendingInputCount", "routeIds", "surfaceKinds", "participants", "metadata" ], "additionalProperties": false }, { "type": "null" } ] }, "message": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "routeId": { "type": "string" }, "agentId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "sessionId", "role", "body", "createdAt", "metadata" ], "additionalProperties": false }, "input": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "intent": { "type": "string", "enum": [ "submit", "steer", "follow-up" ] }, "state": { "type": "string", "enum": [ "queued", "delivered", "spawned", "completed", "cancelled", "failed", "rejected" ] }, "correlationId": { "type": "string" }, "causationId": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "threadId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "activeAgentId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "error": { "type": "string" } }, "required": [ "id", "sessionId", "intent", "state", "correlationId", "body", "createdAt", "updatedAt", "metadata" ], "additionalProperties": false }, "mode": { "type": "string", "enum": [ "spawn", "continued-live", "queued-follow-up", "queued-for-surface", "rejected" ] }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "session", "message", "input", "mode", "agentId" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "allowSpawnFallback": { "type": "boolean" } }, "required": [ "body" ], "additionalProperties": true } } } } } }, "/api/sessions/{sessionId}/tool-calls/{callId}/cancel": { "post": { "operationId": "sessions.toolCalls.cancel", "summary": "Cancel One In-Flight Tool Call", "description": "Cancel a single running tool call by its callId, leaving the turn and any other running calls untouched. The cancelled call settles as a structured \"cancelled by user\" tool result the model adapts to in the same turn, distinct from a whole-turn interrupt. Only the daemon's live local runtime session is controllable; any other session id is a 404 SESSION_NOT_LOCAL, and an unknown or already-settled callId is a 404 TOOL_CALL_NOT_RUNNING.", "tags": [ "sessions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "callId": { "type": "string" }, "cancelled": { "type": "boolean" } }, "required": [ "sessionId", "callId", "cancelled" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "callId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "callId": { "type": "string" } }, "required": [ "sessionId", "callId" ], "additionalProperties": false } } } } } }, "/api/security-settings": { "get": { "operationId": "security.settings", "summary": "Security Settings Report", "description": "Return security-relevant settings, defaults, current state, and enablement tradeoffs.", "tags": [ "settings" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "setting", "configuration" ] }, "featureId": { "type": "string" }, "defaultState": { "type": "string" }, "currentState": { "type": "string" }, "securityRelevant": { "type": "boolean" }, "summary": { "type": "string" }, "insecureWhen": { "type": "string" }, "enablementEffect": { "type": "string" }, "enablementRequirements": { "type": "array", "items": { "type": "string" } }, "operationalNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "type", "featureId", "defaultState", "currentState", "securityRelevant", "summary", "insecureWhen", "enablementEffect", "enablementRequirements", "operationalNotes" ], "additionalProperties": false } } }, "required": [ "settings" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:settings" ] } }, "/api/settings": { "get": { "operationId": "settings.snapshot", "summary": "Settings Snapshot", "description": "Return the settings integration snapshot.", "tags": [ "settings" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "available", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "available": { "type": "boolean" }, "liveKeyCount": { "type": "number" }, "profileCount": { "type": "number" }, "managedLockCount": { "type": "number" }, "resolvedCounts": { "type": "object", "additionalProperties": { "type": "number" } }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "localValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "incomingValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "source": { "type": "string", "enum": [ "synced" ] }, "path": { "type": "string" }, "updatedAt": { "type": "number" } }, "required": [ "key", "localValue", "incomingValue", "source", "path", "updatedAt" ], "additionalProperties": false } }, "recentFailures": { "type": "array", "items": { "type": "object", "properties": { "surface": { "type": "string" }, "message": { "type": "string" }, "timestamp": { "type": "number" } }, "required": [ "surface", "message", "timestamp" ], "additionalProperties": false } }, "stagedManagedBundle": { "type": "object", "properties": { "id": { "type": "string" }, "profileName": { "type": "string" }, "path": { "type": "string" }, "importedAt": { "type": "number" }, "changeCount": { "type": "number" }, "risk": { "type": "string", "enum": [ "low", "medium", "high" ] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "previousValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "nextValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "changed": { "type": "boolean" }, "locked": { "type": "boolean" }, "source": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "key", "previousValue", "nextValue", "changed", "locked", "source", "reason" ], "additionalProperties": false } } }, "required": [ "id", "profileName", "path", "importedAt", "changeCount", "risk", "changes" ], "additionalProperties": false }, "rollbackHistory": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "profileName": { "type": "string" }, "path": { "type": "string" }, "appliedAt": { "type": "number" }, "restoredKeys": { "type": "array", "items": { "type": "string" } }, "previousValues": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "token", "profileName", "path", "appliedAt", "restoredKeys", "previousValues" ], "additionalProperties": false } } }, "required": [ "available", "liveKeyCount", "profileCount", "managedLockCount", "resolvedCounts", "conflicts", "recentFailures", "rollbackHistory" ], "additionalProperties": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:settings" ] } }, "/api/skills": { "post": { "operationId": "skills.create", "summary": "Create Skill", "description": "Create a new skill from a name, one-line description, and Markdown body (plus optional frontmatter metadata). Fails with a conflict when a skill of that name already exists, use skills.update to change an existing one.", "tags": [ "skills" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "updatedAt": { "type": "number" }, "body": { "type": "string" } }, "required": [ "name", "description", "metadata", "body" ], "additionalProperties": false } }, "required": [ "skill" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:skills" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "name", "description", "body" ], "additionalProperties": false } } } } }, "get": { "operationId": "skills.list", "summary": "List Skills", "description": "Return the index line (name, description, metadata) of every skill in the canonical store. Progressive disclosure: bodies are never returned here, call skills.get for the one skill you decide to open.", "tags": [ "skills" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "updatedAt": { "type": "number" } }, "required": [ "name", "description", "metadata" ], "additionalProperties": false } } }, "required": [ "skills" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:skills" ] } }, "/api/skills/{name}": { "delete": { "operationId": "skills.delete", "summary": "Delete Skill", "description": "Permanently delete a skill. Delete means delete: the document is removed, not tombstoned. Returns { deleted: false } when no skill with that name existed, an honest boolean, never a 200 that pretends a phantom skill was removed.", "tags": [ "skills" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "name", "deleted" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:skills" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "get": { "operationId": "skills.get", "summary": "Get Skill", "description": "Return one skill in full, including its Markdown body. Returns 404 when no skill with that name exists.", "tags": [ "skills" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "updatedAt": { "type": "number" }, "body": { "type": "string" } }, "required": [ "name", "description", "metadata", "body" ], "additionalProperties": false } }, "required": [ "skill" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:skills" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/skills/{name}/update": { "post": { "operationId": "skills.update", "summary": "Update Skill", "description": "Update an existing skill's description, body, and/or frontmatter metadata. Absent fields are left unchanged. Returns 404 when no skill with that name exists.", "tags": [ "skills" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "updatedAt": { "type": "number" }, "body": { "type": "string" } }, "required": [ "name", "description", "metadata", "body" ], "additionalProperties": false } }, "required": [ "skill" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:skills" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/api/tasks/{taskId}/cancel": { "post": { "operationId": "tasks.cancel", "summary": "Cancel Runtime Task", "description": "Cancel an in-flight runtime task.", "tags": [ "tasks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "retried": { "type": "boolean" }, "task": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "exec", "agent", "acp", "scheduler", "daemon", "mcp", "plugin", "integration" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "blocked", "completed", "failed", "cancelled" ] }, "owner": { "type": "string" }, "cancellable": { "type": "boolean" }, "parentTaskId": { "type": "string" }, "childTaskIds": { "type": "array", "items": { "type": "string" } }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "currentAttempt": { "type": "number" }, "delayMs": { "type": "number" }, "backoff": { "type": "string", "enum": [ "fixed", "exponential" ] }, "retryOn": { "type": "array", "items": { "type": "string", "enum": [ "network", "timeout", "transient", "tool_error" ] } } }, "required": [ "maxAttempts", "currentAttempt", "delayMs", "backoff", "retryOn" ], "additionalProperties": false }, "retryDelayMs": { "type": "number" }, "retryAt": { "type": "number" }, "exitCode": { "type": "number" }, "error": { "type": "string" }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "correlationId": { "type": "string" }, "turnId": { "type": "string" } }, "required": [ "id", "kind", "title", "status", "owner", "cancellable", "childTaskIds", "queuedAt" ], "additionalProperties": false }, "agentId": { "type": "string" } }, "required": [ "task" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" } }, "required": [ "taskId" ], "additionalProperties": false } } } } } }, "/task": { "post": { "operationId": "tasks.create", "summary": "Create Task", "description": "Submit a task to the daemon or a shared session.", "tags": [ "tasks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledged": { "type": "boolean" }, "mode": { "type": "string" }, "sessionId": { "type": "string" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "task": { "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tools": { "type": "array", "items": { "type": "string" } } }, "required": [ "acknowledged" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "string" }, "model": { "type": "string" }, "tools": { "type": "array", "items": { "type": "string" } }, "provider": { "type": "string" }, "routing": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "providerSelection": { "type": "string", "enum": [ "inherit-current", "concrete", "synthetic" ] }, "providerFailurePolicy": { "type": "string", "enum": [ "ordered-fallbacks", "fail" ] }, "fallbackModels": { "type": "array", "items": { "type": "string" } }, "helperModel": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" } }, "required": [ "providerId", "modelId" ], "additionalProperties": false }, "executionIntent": { "type": "object", "properties": { "riskClass": { "type": "string", "enum": [ "safe", "elevated", "dangerous" ] }, "requiresApproval": { "type": "boolean" }, "networkPolicy": { "type": "string", "enum": [ "inherit", "allow", "deny", "scoped" ] }, "filesystemPolicy": { "type": "string", "enum": [ "inherit", "workspace-write", "read-only", "isolated" ] } }, "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "string" } }, "reasoningEffort": { "type": "string", "enum": [ "none", "instant", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "additionalProperties": false }, "sessionId": { "type": "string" }, "routeId": { "type": "string" }, "surfaceKind": { "type": "string" }, "surfaceId": { "type": "string" }, "externalId": { "type": "string" }, "threadId": { "type": "string" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "title": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "task" ], "additionalProperties": true } } } } } }, "/api/tasks/{taskId}": { "get": { "operationId": "tasks.get", "summary": "Get Runtime Task", "description": "Return a single runtime task record.", "tags": [ "tasks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "exec", "agent", "acp", "scheduler", "daemon", "mcp", "plugin", "integration" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "blocked", "completed", "failed", "cancelled" ] }, "owner": { "type": "string" }, "cancellable": { "type": "boolean" }, "parentTaskId": { "type": "string" }, "childTaskIds": { "type": "array", "items": { "type": "string" } }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "currentAttempt": { "type": "number" }, "delayMs": { "type": "number" }, "backoff": { "type": "string", "enum": [ "fixed", "exponential" ] }, "retryOn": { "type": "array", "items": { "type": "string", "enum": [ "network", "timeout", "transient", "tool_error" ] } } }, "required": [ "maxAttempts", "currentAttempt", "delayMs", "backoff", "retryOn" ], "additionalProperties": false }, "retryDelayMs": { "type": "number" }, "retryAt": { "type": "number" }, "exitCode": { "type": "number" }, "error": { "type": "string" }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "correlationId": { "type": "string" }, "turnId": { "type": "string" } }, "required": [ "id", "kind", "title", "status", "owner", "cancellable", "childTaskIds", "queuedAt" ], "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/tasks": { "get": { "operationId": "tasks.list", "summary": "List Runtime Tasks", "description": "Return the integration snapshot for runtime tasks.", "tags": [ "tasks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "number" }, "running": { "type": "number" }, "blocked": { "type": "number" }, "totals": { "type": "object", "properties": { "created": { "type": "number" }, "completed": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" } }, "required": [ "created", "completed", "failed", "cancelled" ], "additionalProperties": false }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "exec", "agent", "acp", "scheduler", "daemon", "mcp", "plugin", "integration" ] }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "blocked", "completed", "failed", "cancelled" ] }, "owner": { "type": "string" }, "parentTaskId": { "type": "string" }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "error": { "type": "string" } }, "required": [ "id", "kind", "title", "status", "owner", "queuedAt" ], "additionalProperties": false } } }, "required": [ "queued", "running", "blocked", "totals", "tasks" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:tasks" ] } }, "/api/tasks/{taskId}/retry": { "post": { "operationId": "tasks.retry", "summary": "Retry Runtime Task", "description": "Retry a runtime task through the task action endpoint.", "tags": [ "tasks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "retried": { "type": "boolean" }, "task": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "exec", "agent", "acp", "scheduler", "daemon", "mcp", "plugin", "integration" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "blocked", "completed", "failed", "cancelled" ] }, "owner": { "type": "string" }, "cancellable": { "type": "boolean" }, "parentTaskId": { "type": "string" }, "childTaskIds": { "type": "array", "items": { "type": "string" } }, "queuedAt": { "type": "number" }, "startedAt": { "type": "number" }, "endedAt": { "type": "number" }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "number" }, "currentAttempt": { "type": "number" }, "delayMs": { "type": "number" }, "backoff": { "type": "string", "enum": [ "fixed", "exponential" ] }, "retryOn": { "type": "array", "items": { "type": "string", "enum": [ "network", "timeout", "transient", "tool_error" ] } } }, "required": [ "maxAttempts", "currentAttempt", "delayMs", "backoff", "retryOn" ], "additionalProperties": false }, "retryDelayMs": { "type": "number" }, "retryAt": { "type": "number" }, "exitCode": { "type": "number" }, "error": { "type": "string" }, "result": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "correlationId": { "type": "string" }, "turnId": { "type": "string" } }, "required": [ "id", "kind", "title", "status", "owner", "cancellable", "childTaskIds", "queuedAt" ], "additionalProperties": false }, "agentId": { "type": "string" } }, "required": [ "task" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" } }, "required": [ "taskId" ], "additionalProperties": false } } } } } }, "/task/{agentId}": { "get": { "operationId": "tasks.status", "summary": "Get Task Status", "description": "Return lightweight runtime task status by agent id.", "tags": [ "tasks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "task": { "type": "string" }, "status": { "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tools": { "type": "array", "items": { "type": "string" } }, "durationMs": { "type": "number" }, "toolCallCount": { "type": "number" }, "progress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "agentId", "task", "status", "model", "tools", "durationMs", "toolCallCount", "progress", "error" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:tasks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/telemetry/errors": { "get": { "operationId": "telemetry.errors.list", "summary": "List Telemetry Errors", "description": "Return telemetry records that include normalized error metadata.", "tags": [ "telemetry" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "view": { "type": "string", "enum": [ "safe", "raw" ] }, "rawAccessible": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "type": { "type": "string" }, "timestamp": { "type": "number" }, "severity": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] }, "traceId": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "agentId": { "type": "string" }, "taskId": { "type": "string" }, "source": { "type": "string" }, "message": { "type": "string" }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "error": { "type": "object", "properties": { "name": { "type": "string" }, "message": { "type": "string" }, "summary": { "type": "string" }, "hint": { "type": "string" }, "code": { "type": "string" }, "category": { "type": "string", "enum": [ "authentication", "authorization", "billing", "rate_limit", "timeout", "network", "bad_request", "not_found", "permission", "tool", "config", "protocol", "service", "internal", "unknown" ] }, "source": { "type": "string", "enum": [ "provider", "tool", "transport", "config", "permission", "runtime", "render", "acp", "unknown" ] }, "recoverable": { "type": "boolean" }, "statusCode": { "type": "number" }, "provider": { "type": "string" }, "operation": { "type": "string" }, "phase": { "type": "string" }, "requestId": { "type": "string" }, "providerCode": { "type": "string" }, "providerType": { "type": "string" }, "retryAfterMs": { "type": "number" } }, "required": [ "name", "message", "summary", "category", "source", "recoverable" ], "additionalProperties": false } }, "required": [ "id", "domain", "type", "timestamp", "severity", "traceId", "sessionId", "source", "message", "payload", "attributes" ], "additionalProperties": false } }, "pageInfo": { "type": "object", "properties": { "limit": { "type": "number" }, "returned": { "type": "number" }, "hasMore": { "type": "boolean" }, "cursor": { "type": "string" }, "nextCursor": { "type": "string" } }, "required": [ "limit", "returned", "hasMore" ], "additionalProperties": false } }, "required": [ "version", "view", "rawAccessible", "items", "pageInfo" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:telemetry" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "traceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "turnId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "safe", "raw" ] } } ] } }, "/api/v1/telemetry/events": { "get": { "operationId": "telemetry.events.list", "summary": "List Telemetry Events", "description": "Return a paginated telemetry event feed with cursor-based resume semantics.", "tags": [ "telemetry" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "view": { "type": "string", "enum": [ "safe", "raw" ] }, "rawAccessible": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "type": { "type": "string" }, "timestamp": { "type": "number" }, "severity": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] }, "traceId": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "agentId": { "type": "string" }, "taskId": { "type": "string" }, "source": { "type": "string" }, "message": { "type": "string" }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "error": { "type": "object", "properties": { "name": { "type": "string" }, "message": { "type": "string" }, "summary": { "type": "string" }, "hint": { "type": "string" }, "code": { "type": "string" }, "category": { "type": "string", "enum": [ "authentication", "authorization", "billing", "rate_limit", "timeout", "network", "bad_request", "not_found", "permission", "tool", "config", "protocol", "service", "internal", "unknown" ] }, "source": { "type": "string", "enum": [ "provider", "tool", "transport", "config", "permission", "runtime", "render", "acp", "unknown" ] }, "recoverable": { "type": "boolean" }, "statusCode": { "type": "number" }, "provider": { "type": "string" }, "operation": { "type": "string" }, "phase": { "type": "string" }, "requestId": { "type": "string" }, "providerCode": { "type": "string" }, "providerType": { "type": "string" }, "retryAfterMs": { "type": "number" } }, "required": [ "name", "message", "summary", "category", "source", "recoverable" ], "additionalProperties": false } }, "required": [ "id", "domain", "type", "timestamp", "severity", "traceId", "sessionId", "source", "message", "payload", "attributes" ], "additionalProperties": false } }, "pageInfo": { "type": "object", "properties": { "limit": { "type": "number" }, "returned": { "type": "number" }, "hasMore": { "type": "boolean" }, "cursor": { "type": "string" }, "nextCursor": { "type": "string" } }, "required": [ "limit", "returned", "hasMore" ], "additionalProperties": false } }, "required": [ "version", "view", "rawAccessible", "items", "pageInfo" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:telemetry" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "traceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "turnId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "safe", "raw" ] } } ] } }, "/api/v1/telemetry/metrics": { "get": { "operationId": "telemetry.metrics.get", "summary": "Telemetry Metrics", "description": "Return telemetry aggregates and runtime metrics without recent record payloads.", "tags": [ "telemetry" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "view": { "type": "string", "enum": [ "safe", "raw" ] }, "rawAccessible": { "type": "boolean" }, "generatedAt": { "type": "number" }, "runtime": { "type": "object", "properties": { "sessionId": { "type": "string" }, "sessionStatus": { "type": "string" }, "traceContext": { "type": "object", "properties": { "traceId": { "type": "string" }, "rootSpanId": { "type": "string" }, "exportActive": { "type": "boolean" }, "endpoint": { "type": "string" } }, "required": [ "traceId", "rootSpanId", "exportActive" ], "additionalProperties": false }, "sessionCorrelationId": { "type": "string" }, "currentTurnCorrelationId": { "type": "string" }, "dbAvailable": { "type": "boolean" }, "dbPath": { "type": "string" }, "tasks": { "type": "object", "properties": { "total": { "type": "number" }, "queued": { "type": "number" }, "running": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "total", "queued", "running", "blocked" ], "additionalProperties": false }, "agents": { "type": "object", "properties": { "total": { "type": "number" }, "active": { "type": "number" } }, "required": [ "total", "active" ], "additionalProperties": false }, "approvals": { "type": "object", "properties": { "pending": { "type": "number" } }, "required": [ "pending" ], "additionalProperties": false } }, "required": [ "sessionId", "sessionStatus", "sessionCorrelationId", "dbAvailable", "tasks", "agents", "approvals" ], "additionalProperties": false }, "sessionMetrics": { "type": "object", "properties": { "turns": { "type": "number" }, "toolCalls": { "type": "number" }, "toolErrors": { "type": "number" }, "agentsSpawned": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "permissionPrompts": { "type": "number" }, "permissionDenials": { "type": "number" }, "errors": { "type": "number" }, "warnings": { "type": "number" } }, "required": [ "turns", "toolCalls", "toolErrors", "agentsSpawned", "inputTokens", "outputTokens", "cacheReadTokens", "permissionPrompts", "permissionDenials", "errors", "warnings" ], "additionalProperties": false }, "aggregates": { "type": "object", "properties": { "totalEvents": { "type": "number" }, "totalErrors": { "type": "number" }, "totalWarnings": { "type": "number" }, "totalSpans": { "type": "number" }, "byDomain": { "type": "object", "additionalProperties": { "type": "number" } }, "byEventType": { "type": "object", "additionalProperties": { "type": "number" } }, "errorsByCategory": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "totalEvents", "totalErrors", "totalWarnings", "totalSpans", "byDomain", "byEventType", "errorsByCategory" ], "additionalProperties": false } }, "required": [ "version", "view", "rawAccessible", "generatedAt", "runtime", "sessionMetrics", "aggregates" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:telemetry" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "traceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "turnId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "safe", "raw" ] } } ] } }, "/api/v1/telemetry/otlp/v1/logs": { "get": { "operationId": "telemetry.otlp.logs", "summary": "OTLP Log Export", "description": "Return telemetry events encoded as OTLP-compatible log documents.", "tags": [ "telemetry" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceLogs": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } } }, "required": [ "resourceLogs" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:telemetry" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "traceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "turnId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "safe", "raw" ] } } ] } }, "/api/v1/telemetry/otlp/v1/metrics": { "get": { "operationId": "telemetry.otlp.metrics", "summary": "OTLP Metric Export", "description": "Return telemetry metrics encoded as OTLP-compatible metric documents.", "tags": [ "telemetry" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } } }, "required": [ "resourceMetrics" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:telemetry" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "traceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "turnId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "safe", "raw" ] } } ] } }, "/api/v1/telemetry/otlp/v1/traces": { "get": { "operationId": "telemetry.otlp.traces", "summary": "OTLP Trace Export", "description": "Return telemetry traces encoded as OTLP-compatible JSON.", "tags": [ "telemetry" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceSpans": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, {}, { "type": "array", "items": {} } ] } } } }, "required": [ "resourceSpans" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:telemetry" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "traceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "turnId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "safe", "raw" ] } } ] } }, "/api/v1/telemetry": { "get": { "operationId": "telemetry.snapshot", "summary": "Telemetry Snapshot", "description": "Return the current telemetry snapshot with aggregates, runtime state, and recent records.", "tags": [ "telemetry" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "view": { "type": "string", "enum": [ "safe", "raw" ] }, "rawAccessible": { "type": "boolean" }, "generatedAt": { "type": "number" }, "service": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "version" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "signals": { "type": "object", "properties": { "events": { "type": "boolean" }, "errors": { "type": "boolean" }, "metrics": { "type": "boolean" }, "traces": { "type": "boolean" } }, "required": [ "events", "errors", "metrics", "traces" ], "additionalProperties": false }, "encodings": { "type": "object", "properties": { "json": { "type": "boolean" }, "sse": { "type": "boolean" }, "otlpJson": { "type": "object", "properties": { "traces": { "type": "boolean" }, "metrics": { "type": "boolean" }, "logs": { "type": "boolean" } }, "required": [ "traces", "metrics", "logs" ], "additionalProperties": false } }, "required": [ "json", "sse", "otlpJson" ], "additionalProperties": false } }, "required": [ "signals", "encodings" ], "additionalProperties": false }, "runtime": { "type": "object", "properties": { "sessionId": { "type": "string" }, "sessionStatus": { "type": "string" }, "traceContext": { "type": "object", "properties": { "traceId": { "type": "string" }, "rootSpanId": { "type": "string" }, "exportActive": { "type": "boolean" }, "endpoint": { "type": "string" } }, "required": [ "traceId", "rootSpanId", "exportActive" ], "additionalProperties": false }, "sessionCorrelationId": { "type": "string" }, "currentTurnCorrelationId": { "type": "string" }, "dbAvailable": { "type": "boolean" }, "dbPath": { "type": "string" }, "tasks": { "type": "object", "properties": { "total": { "type": "number" }, "queued": { "type": "number" }, "running": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "total", "queued", "running", "blocked" ], "additionalProperties": false }, "agents": { "type": "object", "properties": { "total": { "type": "number" }, "active": { "type": "number" } }, "required": [ "total", "active" ], "additionalProperties": false }, "approvals": { "type": "object", "properties": { "pending": { "type": "number" } }, "required": [ "pending" ], "additionalProperties": false } }, "required": [ "sessionId", "sessionStatus", "sessionCorrelationId", "dbAvailable", "tasks", "agents", "approvals" ], "additionalProperties": false }, "sessionMetrics": { "type": "object", "properties": { "turns": { "type": "number" }, "toolCalls": { "type": "number" }, "toolErrors": { "type": "number" }, "agentsSpawned": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "permissionPrompts": { "type": "number" }, "permissionDenials": { "type": "number" }, "errors": { "type": "number" }, "warnings": { "type": "number" } }, "required": [ "turns", "toolCalls", "toolErrors", "agentsSpawned", "inputTokens", "outputTokens", "cacheReadTokens", "permissionPrompts", "permissionDenials", "errors", "warnings" ], "additionalProperties": false }, "aggregates": { "type": "object", "properties": { "totalEvents": { "type": "number" }, "totalErrors": { "type": "number" }, "totalWarnings": { "type": "number" }, "totalSpans": { "type": "number" }, "byDomain": { "type": "object", "additionalProperties": { "type": "number" } }, "byEventType": { "type": "object", "additionalProperties": { "type": "number" } }, "errorsByCategory": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "totalEvents", "totalErrors", "totalWarnings", "totalSpans", "byDomain", "byEventType", "errorsByCategory" ], "additionalProperties": false }, "recent": { "type": "object", "properties": { "events": { "type": "object", "properties": { "version": { "type": "number" }, "view": { "type": "string", "enum": [ "safe", "raw" ] }, "rawAccessible": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "type": { "type": "string" }, "timestamp": { "type": "number" }, "severity": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] }, "traceId": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "agentId": { "type": "string" }, "taskId": { "type": "string" }, "source": { "type": "string" }, "message": { "type": "string" }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "error": { "type": "object", "properties": { "name": { "type": "string" }, "message": { "type": "string" }, "summary": { "type": "string" }, "hint": { "type": "string" }, "code": { "type": "string" }, "category": { "type": "string", "enum": [ "authentication", "authorization", "billing", "rate_limit", "timeout", "network", "bad_request", "not_found", "permission", "tool", "config", "protocol", "service", "internal", "unknown" ] }, "source": { "type": "string", "enum": [ "provider", "tool", "transport", "config", "permission", "runtime", "render", "acp", "unknown" ] }, "recoverable": { "type": "boolean" }, "statusCode": { "type": "number" }, "provider": { "type": "string" }, "operation": { "type": "string" }, "phase": { "type": "string" }, "requestId": { "type": "string" }, "providerCode": { "type": "string" }, "providerType": { "type": "string" }, "retryAfterMs": { "type": "number" } }, "required": [ "name", "message", "summary", "category", "source", "recoverable" ], "additionalProperties": false } }, "required": [ "id", "domain", "type", "timestamp", "severity", "traceId", "sessionId", "source", "message", "payload", "attributes" ], "additionalProperties": false } }, "pageInfo": { "type": "object", "properties": { "limit": { "type": "number" }, "returned": { "type": "number" }, "hasMore": { "type": "boolean" }, "cursor": { "type": "string" }, "nextCursor": { "type": "string" } }, "required": [ "limit", "returned", "hasMore" ], "additionalProperties": false } }, "required": [ "version", "view", "rawAccessible", "items", "pageInfo" ], "additionalProperties": false }, "errors": { "type": "object", "properties": { "version": { "type": "number" }, "view": { "type": "string", "enum": [ "safe", "raw" ] }, "rawAccessible": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "type": { "type": "string" }, "timestamp": { "type": "number" }, "severity": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] }, "traceId": { "type": "string" }, "sessionId": { "type": "string" }, "turnId": { "type": "string" }, "agentId": { "type": "string" }, "taskId": { "type": "string" }, "source": { "type": "string" }, "message": { "type": "string" }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "error": { "type": "object", "properties": { "name": { "type": "string" }, "message": { "type": "string" }, "summary": { "type": "string" }, "hint": { "type": "string" }, "code": { "type": "string" }, "category": { "type": "string", "enum": [ "authentication", "authorization", "billing", "rate_limit", "timeout", "network", "bad_request", "not_found", "permission", "tool", "config", "protocol", "service", "internal", "unknown" ] }, "source": { "type": "string", "enum": [ "provider", "tool", "transport", "config", "permission", "runtime", "render", "acp", "unknown" ] }, "recoverable": { "type": "boolean" }, "statusCode": { "type": "number" }, "provider": { "type": "string" }, "operation": { "type": "string" }, "phase": { "type": "string" }, "requestId": { "type": "string" }, "providerCode": { "type": "string" }, "providerType": { "type": "string" }, "retryAfterMs": { "type": "number" } }, "required": [ "name", "message", "summary", "category", "source", "recoverable" ], "additionalProperties": false } }, "required": [ "id", "domain", "type", "timestamp", "severity", "traceId", "sessionId", "source", "message", "payload", "attributes" ], "additionalProperties": false } }, "pageInfo": { "type": "object", "properties": { "limit": { "type": "number" }, "returned": { "type": "number" }, "hasMore": { "type": "boolean" }, "cursor": { "type": "string" }, "nextCursor": { "type": "string" } }, "required": [ "limit", "returned", "hasMore" ], "additionalProperties": false } }, "required": [ "version", "view", "rawAccessible", "items", "pageInfo" ], "additionalProperties": false }, "spans": { "type": "object", "properties": { "version": { "type": "number" }, "view": { "type": "string", "enum": [ "safe", "raw" ] }, "rawAccessible": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "number" }, "spanContext": { "type": "object", "properties": { "traceId": { "type": "string" }, "spanId": { "type": "string" }, "isValid": { "type": "boolean" } }, "required": [ "traceId", "spanId", "isValid" ], "additionalProperties": false }, "parentSpanId": { "type": "string" }, "startTimeMs": { "type": "number" }, "endTimeMs": { "type": "number" }, "durationMs": { "type": "number" }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "events": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "timestamp": { "type": "number" }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "name", "timestamp" ], "additionalProperties": false } }, "status": { "type": "object", "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code" ], "additionalProperties": false }, "instrumentationScope": { "type": "string" } }, "required": [ "name", "kind", "spanContext", "startTimeMs", "endTimeMs", "durationMs", "attributes", "events", "status", "instrumentationScope" ], "additionalProperties": false } }, "pageInfo": { "type": "object", "properties": { "limit": { "type": "number" }, "returned": { "type": "number" }, "hasMore": { "type": "boolean" }, "cursor": { "type": "string" }, "nextCursor": { "type": "string" } }, "required": [ "limit", "returned", "hasMore" ], "additionalProperties": false } }, "required": [ "version", "view", "rawAccessible", "items", "pageInfo" ], "additionalProperties": false } }, "required": [ "events", "errors", "spans" ], "additionalProperties": false } }, "required": [ "version", "view", "rawAccessible", "generatedAt", "service", "capabilities", "runtime", "sessionMetrics", "aggregates", "recent" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:telemetry" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "traceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "turnId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "safe", "raw" ] } } ] } }, "/api/v1/telemetry/stream": { "get": { "operationId": "telemetry.stream", "summary": "Telemetry Event Stream", "description": "Open the telemetry SSE stream and emit a ready event with resume metadata.", "tags": [ "telemetry" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "capabilities": { "type": "object", "properties": { "signals": { "type": "object", "properties": { "events": { "type": "boolean" }, "errors": { "type": "boolean" }, "metrics": { "type": "boolean" }, "traces": { "type": "boolean" } }, "required": [ "events", "errors", "metrics", "traces" ], "additionalProperties": false }, "encodings": { "type": "object", "properties": { "json": { "type": "boolean" }, "sse": { "type": "boolean" }, "otlpJson": { "type": "object", "properties": { "traces": { "type": "boolean" }, "metrics": { "type": "boolean" }, "logs": { "type": "boolean" } }, "required": [ "traces", "metrics", "logs" ], "additionalProperties": false } }, "required": [ "json", "sse", "otlpJson" ], "additionalProperties": false } }, "required": [ "signals", "encodings" ], "additionalProperties": false }, "view": { "type": "string", "enum": [ "safe", "raw" ] }, "rawAccessible": { "type": "boolean" }, "resumedFrom": { "type": "string" } }, "required": [ "version", "capabilities", "view", "rawAccessible" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http" ], "x-scopes": [ "read:telemetry" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "traceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "turnId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "safe", "raw" ] } } ] } }, "/api/v1/telemetry/traces": { "get": { "operationId": "telemetry.traces.list", "summary": "List Telemetry Traces", "description": "Return synthesized readable spans derived from runtime telemetry.", "tags": [ "telemetry" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "view": { "type": "string", "enum": [ "safe", "raw" ] }, "rawAccessible": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "number" }, "spanContext": { "type": "object", "properties": { "traceId": { "type": "string" }, "spanId": { "type": "string" }, "isValid": { "type": "boolean" } }, "required": [ "traceId", "spanId", "isValid" ], "additionalProperties": false }, "parentSpanId": { "type": "string" }, "startTimeMs": { "type": "number" }, "endTimeMs": { "type": "number" }, "durationMs": { "type": "number" }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "events": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "timestamp": { "type": "number" }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "name", "timestamp" ], "additionalProperties": false } }, "status": { "type": "object", "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code" ], "additionalProperties": false }, "instrumentationScope": { "type": "string" } }, "required": [ "name", "kind", "spanContext", "startTimeMs", "endTimeMs", "durationMs", "attributes", "events", "status", "instrumentationScope" ], "additionalProperties": false } }, "pageInfo": { "type": "object", "properties": { "limit": { "type": "number" }, "returned": { "type": "number" }, "hasMore": { "type": "boolean" }, "cursor": { "type": "string" }, "nextCursor": { "type": "string" } }, "required": [ "limit", "returned", "hasMore" ], "additionalProperties": false } }, "required": [ "version", "view", "rawAccessible", "items", "pageInfo" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:telemetry" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "traceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "turnId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "safe", "raw" ] } } ] } }, "/api/voice/providers": { "get": { "operationId": "voice.providers.list", "summary": "List Voice Providers", "description": "Return registered voice providers.", "tags": [ "voice" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "capabilities" ], "additionalProperties": false } } }, "required": [ "providers" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:voice" ] } }, "/api/voice/realtime/session": { "post": { "operationId": "voice.realtime.session", "summary": "Open Voice Realtime Session", "description": "Open a realtime voice session through a registered voice provider.", "tags": [ "voice" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "sessionId": { "type": "string" }, "transport": { "type": "string" }, "url": { "type": "string" }, "expiresAt": { "type": "number" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "providerId", "sessionId", "transport", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:voice" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "voiceId": { "type": "string" }, "inputFormat": { "type": "string" }, "outputFormat": { "type": "string" }, "instructions": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "additionalProperties": true } } } } } }, "/api/voice": { "get": { "operationId": "voice.status", "summary": "Voice Status", "description": "Return configured voice provider posture and capabilities.", "tags": [ "voice" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "providerCount": { "type": "number" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "configured": { "type": "boolean" }, "detail": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "state", "capabilities", "configured", "metadata" ], "additionalProperties": false } }, "note": { "type": "string" } }, "required": [ "enabled", "providerCount", "providers", "note" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:voice" ] } }, "/api/voice/stt": { "post": { "operationId": "voice.stt", "summary": "Run Speech To Text", "description": "Transcribe an audio artifact through a registered voice provider.", "tags": [ "voice" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "text": { "type": "string" }, "language": { "type": "string" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "confidence": { "type": "number" } }, "required": [ "text" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "providerId", "text", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:voice" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "audio": { "type": "object", "properties": { "mimeType": { "type": "string" }, "format": { "type": "string" }, "dataBase64": { "type": "string" }, "uri": { "type": "string" }, "sampleRateHz": { "type": "number" }, "durationMs": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "mimeType", "format", "metadata" ], "additionalProperties": false }, "language": { "type": "string" }, "modelId": { "type": "string" }, "prompt": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "audio" ], "additionalProperties": true } } } } } }, "/api/voice/tts": { "post": { "operationId": "voice.tts", "summary": "Run Text To Speech", "description": "Synthesize audio through a registered voice provider.", "tags": [ "voice" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "audio": { "type": "object", "properties": { "mimeType": { "type": "string" }, "format": { "type": "string" }, "dataBase64": { "type": "string" }, "uri": { "type": "string" }, "sampleRateHz": { "type": "number" }, "durationMs": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "mimeType", "format", "metadata" ], "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "providerId", "audio", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:voice" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "text": { "type": "string" }, "voiceId": { "type": "string" }, "modelId": { "type": "string" }, "format": { "type": "string" }, "speed": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "text" ], "additionalProperties": true } } } } } }, "/api/voice/tts/stream": { "post": { "operationId": "voice.tts.stream", "summary": "Stream Text To Speech", "description": "Synthesize audio as streamed bytes through a registered streaming voice provider.", "tags": [ "voice" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contentType": { "type": "string" }, "providerId": { "type": "string" }, "format": { "type": "string" } }, "required": [ "contentType", "providerId", "format" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http" ], "x-scopes": [ "write:voice" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "text": { "type": "string" }, "voiceId": { "type": "string" }, "modelId": { "type": "string" }, "format": { "type": "string" }, "speed": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "text" ], "additionalProperties": true } } } } } }, "/api/voice/voices": { "get": { "operationId": "voice.voices.list", "summary": "List Voices", "description": "Return registered voices for a voice provider.", "tags": [ "voice" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "locale": { "type": "string" }, "gender": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "label", "metadata" ], "additionalProperties": false } } }, "required": [ "voices" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:voice" ], "parameters": [ { "name": "providerId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/watchers": { "post": { "operationId": "watchers.create", "summary": "Create Watcher", "description": "Register a new watcher.", "tags": [ "watchers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "intervalMs": { "type": "number" }, "lastHeartbeatAt": { "type": "number" }, "sourceLagMs": { "type": "number" }, "sourceStatus": { "type": "string" }, "degradedReason": { "type": "string" }, "lastCheckpoint": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "state", "source", "metadata" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:watchers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "sourceId": { "type": "string" }, "sourceKind": { "type": "string" }, "intervalMs": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "url": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "endpoint": { "type": "string" }, "address": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "run": { "type": "string" } }, "required": [ "label" ], "additionalProperties": true } } } } }, "get": { "operationId": "watchers.list", "summary": "List Watchers", "description": "Return configured watchers and their runtime posture.", "tags": [ "watchers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "watchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "intervalMs": { "type": "number" }, "lastHeartbeatAt": { "type": "number" }, "sourceLagMs": { "type": "number" }, "sourceStatus": { "type": "string" }, "degradedReason": { "type": "string" }, "lastCheckpoint": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "state", "source", "metadata" ], "additionalProperties": true } } }, "required": [ "watchers" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:watchers" ] } }, "/api/watchers/{watcherId}": { "delete": { "operationId": "watchers.delete", "summary": "Delete Watcher", "description": "Delete an existing watcher.", "tags": [ "watchers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "removed" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:watchers" ], "x-dangerous": true, "parameters": [ { "name": "watcherId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "watchers.update", "summary": "Update Watcher", "description": "Update an existing watcher. (Renamed from watchers.patch in the 1.0.0 core-verb rename, canonical verb is update, not patch.)", "tags": [ "watchers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "intervalMs": { "type": "number" }, "lastHeartbeatAt": { "type": "number" }, "sourceLagMs": { "type": "number" }, "sourceStatus": { "type": "string" }, "degradedReason": { "type": "string" }, "lastCheckpoint": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "state", "source", "metadata" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:watchers" ], "parameters": [ { "name": "watcherId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watcherId": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "sourceId": { "type": "string" }, "sourceKind": { "type": "string" }, "enabled": { "type": "boolean" }, "intervalMs": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "url": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "endpoint": { "type": "string" }, "address": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "run": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/watchers/{watcherId}/run": { "post": { "operationId": "watchers.run", "summary": "Run Watcher", "description": "Trigger a watcher immediately.", "tags": [ "watchers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "intervalMs": { "type": "number" }, "lastHeartbeatAt": { "type": "number" }, "sourceLagMs": { "type": "number" }, "sourceStatus": { "type": "string" }, "degradedReason": { "type": "string" }, "lastCheckpoint": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "state", "source", "metadata" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:watchers" ], "parameters": [ { "name": "watcherId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watcherId": { "type": "string" } }, "required": [ "watcherId" ], "additionalProperties": false } } } } } }, "/api/watchers/{watcherId}/start": { "post": { "operationId": "watchers.start", "summary": "Start Watcher", "description": "Start a watcher instance.", "tags": [ "watchers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "intervalMs": { "type": "number" }, "lastHeartbeatAt": { "type": "number" }, "sourceLagMs": { "type": "number" }, "sourceStatus": { "type": "string" }, "degradedReason": { "type": "string" }, "lastCheckpoint": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "state", "source", "metadata" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:watchers" ], "parameters": [ { "name": "watcherId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watcherId": { "type": "string" } }, "required": [ "watcherId" ], "additionalProperties": false } } } } } }, "/api/watchers/{watcherId}/stop": { "post": { "operationId": "watchers.stop", "summary": "Stop Watcher", "description": "Stop a watcher instance.", "tags": [ "watchers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "enabled", "createdAt", "updatedAt", "metadata" ], "additionalProperties": true }, "intervalMs": { "type": "number" }, "lastHeartbeatAt": { "type": "number" }, "sourceLagMs": { "type": "number" }, "sourceStatus": { "type": "string" }, "degradedReason": { "type": "string" }, "lastCheckpoint": { "type": "string" }, "lastError": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "id", "kind", "label", "state", "source", "metadata" ], "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "admin", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:watchers" ], "parameters": [ { "name": "watcherId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watcherId": { "type": "string" } }, "required": [ "watcherId" ], "additionalProperties": false } } } } } }, "/api/web-search/providers": { "get": { "operationId": "web_search.providers.list", "summary": "List Web Search Providers", "description": "Return registered web search provider capabilities.", "tags": [ "web-search" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "requiresAuth": { "type": "boolean" }, "configured": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "id", "label", "capabilities", "requiresAuth", "configured" ], "additionalProperties": false } } }, "required": [ "providers" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:web-search" ] } }, "/api/web-search/query": { "post": { "operationId": "web_search.query", "summary": "Run Web Search", "description": "Execute a provider-backed web search and return normalized ranked results.", "tags": [ "web-search" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "providerLabel": { "type": "string" }, "query": { "type": "string" }, "verbosity": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number" }, "url": { "type": "string" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "displayUrl": { "type": "string" }, "domain": { "type": "string" }, "type": { "type": "string" }, "providerId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "extract": { "type": "string" }, "content": { "type": "string" }, "tokensUsed": { "type": "number" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "truncated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "url", "extract", "content", "tokensUsed", "metadata" ], "additionalProperties": false } } }, "required": [ "rank", "url", "type", "providerId", "metadata" ], "additionalProperties": false } }, "instantAnswer": { "type": "object", "properties": { "heading": { "type": "string" }, "answer": { "type": "string" }, "abstract": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string" }, "image": { "type": "string" }, "type": { "type": "string" }, "related": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "url": { "type": "string" } }, "required": [ "text", "url" ], "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "type", "related", "metadata" ], "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] } } }, "required": [ "providerId", "providerLabel", "query", "verbosity", "results", "metadata" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:web-search" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "providerId": { "type": "string" }, "maxResults": { "type": "number" }, "verbosity": { "type": "string" }, "region": { "type": "string" }, "safeSearch": { "type": "string" }, "timeRange": { "type": "string" }, "includeInstantAnswer": { "type": "boolean" }, "includeEvidence": { "type": "boolean" }, "evidenceTopN": { "type": "number" }, "evidenceExtract": { "type": "string" } }, "required": [ "query" ], "additionalProperties": true } } } } } }, "/api/workspaces/registrations": { "post": { "operationId": "workspaces.registrations.add", "summary": "Register a Workspace", "description": "Register a workspace root so the whole subtree beneath it is covered. Refuses an absurdly broad root (the home directory, the filesystem root, or the daemon state directory) with a 400, coverage flows down the entire subtree, so a root that broad would sweep far more than a project. Idempotent: re-registering the same normalized root returns alreadyRegistered:true. Registering a root clears any remembered decline recorded at exactly that root.", "tags": [ "workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "root": { "type": "string" }, "registeredAt": { "type": "string" }, "label": { "type": "string" }, "origin": { "type": "string" }, "checkpointEligible": { "type": "boolean" } }, "required": [ "root", "registeredAt" ], "additionalProperties": false }, "alreadyRegistered": { "type": "boolean" } }, "required": [ "workspace", "alreadyRegistered" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "root": { "type": "string" }, "label": { "type": "string" }, "origin": { "type": "string" }, "checkpointEligible": { "type": "boolean" } }, "required": [ "root" ], "additionalProperties": false } } } } }, "get": { "operationId": "workspaces.registrations.list", "summary": "List Registered Workspaces", "description": "Return every registered workspace root (coverage flows down each root's subtree) and every remembered subtree-scoped decline. Read-only.", "tags": [ "workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "root": { "type": "string" }, "registeredAt": { "type": "string" }, "label": { "type": "string" }, "origin": { "type": "string" }, "checkpointEligible": { "type": "boolean" } }, "required": [ "root", "registeredAt" ], "additionalProperties": false } }, "declines": { "type": "array", "items": { "type": "object", "properties": { "root": { "type": "string" }, "declinedAt": { "type": "string" } }, "required": [ "root", "declinedAt" ], "additionalProperties": false } } }, "required": [ "workspaces", "declines" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:workspaces" ] }, "delete": { "operationId": "workspaces.registrations.remove", "summary": "Unregister a Workspace", "description": "Remove a registered workspace root. Returns { removed: false } when no root with that normalized path was registered, an honest boolean, never a 200 that pretends a phantom root was removed.", "tags": [ "workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "root": { "type": "string" }, "removed": { "type": "boolean" } }, "required": [ "root", "removed" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "write:workspaces" ], "parameters": [ { "name": "root", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/api/workspaces/resolve": { "post": { "operationId": "workspaces.resolve", "summary": "Resolve Workspace Coverage", "description": "Resolve a path against the registry: covered (by which nearest registered root), declined (at which root), or unknown. Coverage flows DOWN a registered root's subtree and is inherited through the git worktree→main-repo link, a linked worktree outside any registered root still resolves to the main repo's registration. When mainWorktreeRoot is omitted the daemon probes the link itself. Read-only.", "tags": [ "workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "status": { "type": "string", "enum": [ "covered", "declined", "unknown" ] }, "coveredBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "declinedRoot": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viaWorktreeLink": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "path", "status", "coveredBy", "declinedRoot", "viaWorktreeLink", "reason" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "mainWorktreeRoot": { "type": "string" } }, "required": [ "path" ], "additionalProperties": false } } } } } }, "/api/worktrees": { "get": { "operationId": "worktrees.snapshot", "summary": "Worktrees Snapshot", "description": "Return the worktree integration snapshot.", "tags": [ "worktrees" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "number" }, "active": { "type": "number" }, "paused": { "type": "number" }, "kept": { "type": "number" }, "discard": { "type": "number" }, "pendingCleanup": { "type": "number" }, "sessionAttached": { "type": "number" }, "taskAttached": { "type": "number" }, "agentOwned": { "type": "number" }, "orchestratorOwned": { "type": "number" }, "manualOwned": { "type": "number" } }, "required": [ "total", "active", "paused", "kept", "discard", "pendingCleanup", "sessionAttached", "taskAttached", "agentOwned", "orchestratorOwned", "manualOwned" ], "additionalProperties": false }, "records": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "orchestrator", "manual" ] }, "state": { "type": "string", "enum": [ "active", "paused", "kept", "discard", "pending-cleanup" ] }, "ownerId": { "type": "string" }, "sessionId": { "type": "string" }, "taskId": { "type": "string" }, "setup": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "skipped", "succeeded", "failed" ] }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "command", "carry-over" ] }, "label": { "type": "string" }, "ok": { "type": "boolean" }, "exitCode": { "type": "number" }, "output": { "type": "string" } }, "required": [ "kind", "label", "ok", "output" ], "additionalProperties": false } }, "error": { "type": "string" } }, "required": [ "state", "startedAt", "completedAt", "steps" ], "additionalProperties": false }, "updatedAt": { "type": "number" } }, "required": [ "path", "kind", "state", "updatedAt" ], "additionalProperties": false } } }, "required": [ "summary", "records" ], "additionalProperties": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-typed-client-io": true, "x-access": "authenticated", "x-transport": [ "http", "ws" ], "x-scopes": [ "read:worktrees" ] } }, "/api/control/gateway-methods/{methodId}/invoke": { "post": { "operationId": "gateway.invoke", "summary": "Invoke a cataloged operator method by id", "description": "The generic invoke endpoint. Every invokable cataloged method is reachable here by its method id; methods WITHOUT a dedicated REST binding (listed in `x-invoke-only-methods`) are reachable ONLY here. Per-method request/response schemas are the same as the per-method entries in `x-operator-methods`.", "tags": [ "gateway" ], "parameters": [ { "name": "methodId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "The method-specific input (see the method's inputSchema)." } } } }, "responses": { "200": { "description": "Method-specific response (see the method's outputSchema).", "content": { "application/json": { "schema": {} } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-invoke-only-methods": [ "acp.agents.list", "acp.sessions.create", "approvals.raise", "channels.test.send", "checkpoints.create", "checkpoints.diff", "checkpoints.list", "checkpoints.restore", "checkpoints.restorePreview", "checkpoints.revertHunk", "checkpoints.revertHunkPreview", "cost.attribution.get", "credentials.delete", "credentials.set", "email.expectation.cancel", "email.expectation.list", "email.expectation.open", "email.inbound.status", "flags.graduation.report", "fleet.archive", "fleet.archiveFinished", "fleet.archived.list", "fleet.attempts.judge", "fleet.attempts.list", "fleet.attempts.pick", "fleet.conflicts.list", "fleet.conflicts.resolve", "fleet.list", "fleet.observed.steer", "fleet.snapshot", "fleet.unarchive", "pairing.handoff.complete", "pairing.handoff.create", "pairing.posture.get", "pairing.tokens.create", "pairing.tokens.delete", "pairing.tokens.list", "pairing.tokens.migrate", "pairing.tokens.rename", "pairing.tokens.revokeShared", "permissions.rules.delete", "permissions.rules.list", "push.subscriptions.create", "push.subscriptions.delete", "push.subscriptions.list", "push.subscriptions.reconcile", "push.subscriptions.verify", "push.vapid.get", "quota.fanout.get", "quota.snapshot.get", "relay.pairing.mint", "relay.reachability.get", "rewind.apply", "rewind.conversation.host.register", "rewind.conversation.host.release", "rewind.conversation.hosts.list", "rewind.conversation.requests.answer", "rewind.conversation.requests.take", "rewind.plan", "sessions.changes.get", "sessions.hosted.attach", "sessions.hosted.create", "sessions.hosted.detach", "sessions.hosted.kill", "sessions.hosted.list", "sessions.search", "tailscale.get", "tailscale.serve.run", "update.check", "update.status", "worktrees.discard", "worktrees.setup.run" ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Operator bearer token (Authorization: Bearer )." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "goodvibes_session", "description": "Login-issued session cookie (see the contract auth.login route)." } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "string" }, "kind": { "type": "string" }, "details": { "type": "object" } }, "required": [ "error" ] } } }, "x-auth-contract": { "modes": [ "shared-bearer", "session-login" ], "login": { "method": "POST", "path": "/login", "requestSchema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "username", "password" ], "additionalProperties": false }, "responseSchema": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "token": { "type": "string" }, "username": { "type": "string" }, "expiresAt": { "type": "number" } }, "required": [ "authenticated", "token", "username", "expiresAt" ], "additionalProperties": false } }, "current": { "method": "GET", "path": "/api/control-plane/auth", "responseSchema": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "authMode": { "type": "string", "enum": [ "anonymous", "invalid", "session", "shared-token" ] }, "tokenPresent": { "type": "boolean" }, "authorizationHeaderPresent": { "type": "boolean" }, "sessionCookiePresent": { "type": "boolean" }, "principalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "principalKind": { "anyOf": [ { "type": "string", "enum": [ "user", "bot", "service", "token" ] }, { "type": "null" } ] }, "admin": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "authenticated", "authMode", "tokenPresent", "authorizationHeaderPresent", "sessionCookiePresent", "principalId", "principalKind", "admin", "scopes", "roles" ], "additionalProperties": false }, "aliasPaths": [ "/api/control-plane/whoami" ] }, "sessionCookie": { "name": "goodvibes_session", "httpOnly": true, "sameSite": "Lax", "path": "/" }, "bearer": { "header": "Authorization: Bearer ", "queryParameters": [] } }, "x-untyped-client-io-count": 0, "x-operator-methods": [ { "id": "accounts.snapshot", "category": "accounts", "access": "authenticated", "rest": "GET /api/accounts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "acp.agents.list", "category": "acp", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "schema-less", "outputSchemaCoverage": "typed" }, { "id": "acp.sessions.create", "category": "acp", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "approvals.approve", "category": "approvals", "access": "authenticated", "rest": "POST /api/approvals/{approvalId}/approve", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "approvals.cancel", "category": "approvals", "access": "authenticated", "rest": "POST /api/approvals/{approvalId}/cancel", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "approvals.claim", "category": "approvals", "access": "authenticated", "rest": "POST /api/approvals/{approvalId}/claim", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "approvals.deny", "category": "approvals", "access": "authenticated", "rest": "POST /api/approvals/{approvalId}/deny", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "approvals.list", "category": "approvals", "access": "authenticated", "rest": "GET /api/approvals", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "approvals.raise", "category": "approvals", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "artifacts.content.get", "category": "artifacts", "access": "authenticated", "rest": "GET /api/artifacts/{artifactId}/content", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "artifacts.create", "category": "artifacts", "access": "authenticated", "rest": "POST /api/artifacts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "artifacts.get", "category": "artifacts", "access": "authenticated", "rest": "GET /api/artifacts/{artifactId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "artifacts.list", "category": "artifacts", "access": "authenticated", "rest": "GET /api/artifacts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "local_auth.bootstrap.delete", "category": "auth", "access": "admin", "rest": "DELETE /api/local-auth/bootstrap-file", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "local_auth.sessions.delete", "category": "auth", "access": "admin", "rest": "DELETE /api/local-auth/sessions/{sessionId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "local_auth.status", "category": "auth", "access": "admin", "rest": "GET /api/local-auth", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "local_auth.users.create", "category": "auth", "access": "admin", "rest": "POST /api/local-auth/users", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "local_auth.users.delete", "category": "auth", "access": "admin", "rest": "DELETE /api/local-auth/users/{username}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "local_auth.users.password.rotate", "category": "auth", "access": "admin", "rest": "POST /api/local-auth/users/{username}/password", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.heartbeat.list", "category": "automation", "access": "authenticated", "rest": "GET /api/automation/heartbeat", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.heartbeat.run", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/heartbeat", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.integration.snapshot", "category": "automation", "access": "authenticated", "rest": "GET /api/automation", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.jobs.create", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/jobs", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.jobs.delete", "category": "automation", "access": "authenticated", "rest": "DELETE /api/automation/jobs/{jobId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.jobs.disable", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/jobs/{jobId}/disable", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.jobs.enable", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/jobs/{jobId}/enable", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.jobs.list", "category": "automation", "access": "authenticated", "rest": "GET /api/automation/jobs", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.jobs.run", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/jobs/{jobId}/run", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.jobs.update", "category": "automation", "access": "authenticated", "rest": "PATCH /api/automation/jobs/{jobId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.runs.cancel", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/runs/{runId}/cancel", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.runs.get", "category": "automation", "access": "authenticated", "rest": "GET /api/automation/runs/{runId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.runs.list", "category": "automation", "access": "authenticated", "rest": "GET /api/automation/runs", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.runs.retry", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/runs/{runId}/retry", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.schedules.create", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/schedules", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.schedules.delete", "category": "automation", "access": "authenticated", "rest": "DELETE /api/automation/schedules/{scheduleId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.schedules.disable", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/schedules/{scheduleId}/disable", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.schedules.enable", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/schedules/{scheduleId}/enable", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.schedules.list", "category": "automation", "access": "authenticated", "rest": "GET /api/automation/schedules", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "automation.schedules.run", "category": "automation", "access": "authenticated", "rest": "POST /api/automation/schedules/{scheduleId}/run", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.click", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/click", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.extract", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/extract", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.history.back", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/history/back", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.history.forward", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/history/forward", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.navigate", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/navigate", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.press", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/press", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.provision", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/provision", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.readText", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/read-text", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.screenshot", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/screenshot", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.scroll", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/scroll", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.select", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/select", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.sessions.attach", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/sessions/attach", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.sessions.close", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/sessions/close", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.sessions.launch", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/sessions/launch", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.sessions.list", "category": "browser", "access": "authenticated", "rest": "GET /api/browser/sessions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.sessions.release", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/sessions/release", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.snapshot", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/snapshot", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.status", "category": "browser", "access": "authenticated", "rest": "GET /api/browser/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.tabs.close", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/tabs/close", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.tabs.create", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/tabs", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.tabs.list", "category": "browser", "access": "authenticated", "rest": "GET /api/browser/tabs", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.tabs.switch", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/tabs/switch", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.type", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/type", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "browser.waitFor", "category": "browser", "access": "authenticated", "rest": "POST /api/browser/wait-for", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "calendar.events.create", "category": "calendar", "access": "admin", "rest": "POST /api/calendar/events", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "calendar.events.get", "category": "calendar", "access": "authenticated", "rest": "GET /api/calendar/events/{eventId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "calendar.events.list", "category": "calendar", "access": "authenticated", "rest": "GET /api/calendar/events", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "calendar.ics.export", "category": "calendar", "access": "authenticated", "rest": "GET /api/calendar/ics/export", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "calendar.ics.import", "category": "calendar", "access": "admin", "rest": "POST /api/calendar/ics/import", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.accounts.action.default", "category": "channels", "access": "admin", "rest": "POST /api/channels/accounts/{surface}/actions/{action}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.accounts.action.named", "category": "channels", "access": "admin", "rest": "POST /api/channels/accounts/{surface}/{accountId}/actions/{action}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.accounts.get", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/accounts/{surface}/{accountId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.accounts.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/accounts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.accounts.surface.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/accounts/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.actions.invoke", "category": "channels", "access": "admin", "rest": "POST /api/channels/actions/{surface}/{actionId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.actions.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/actions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.actions.surface.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/actions/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.agent_tools.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/agent-tools", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.agent_tools.surface.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/agent-tools/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.allowlist.edit", "category": "channels", "access": "admin", "rest": "POST /api/channels/allowlist/{surface}/edit", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.allowlist.resolve", "category": "channels", "access": "admin", "rest": "POST /api/channels/allowlist/{surface}/resolve", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.authorize", "category": "channels", "access": "admin", "rest": "POST /api/channels/authorize/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.capabilities.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/capabilities", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.capabilities.surface.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/capabilities/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.directory.query", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/directory/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.doctor.get", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/doctor/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.drafts.delete", "category": "channels", "access": "admin", "rest": "DELETE /api/channels/drafts/{draftId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.drafts.get", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/drafts/{draftId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.drafts.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/drafts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.drafts.save", "category": "channels", "access": "admin", "rest": "POST /api/channels/drafts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.inbox.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/inbox", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.lifecycle.get", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/lifecycle/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.policies.audit", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/policies/audit", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.policies.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/policies", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.policies.update", "category": "channels", "access": "admin", "rest": "POST /api/channels/policies/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.profiles.delete", "category": "channels", "access": "admin", "rest": "DELETE /api/channels/profiles/{surfaceKind}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.profiles.get", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/profiles/{surfaceKind}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.profiles.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/profiles", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.profiles.set", "category": "channels", "access": "admin", "rest": "POST /api/channels/profiles", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.repairs.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/repair-actions/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.routing.assign", "category": "channels", "access": "admin", "rest": "POST /api/channels/routing", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.routing.delete", "category": "channels", "access": "admin", "rest": "DELETE /api/channels/routing/{assignmentId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.routing.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/routing", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.setup.get", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/setup/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.status", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.targets.resolve", "category": "channels", "access": "admin", "rest": "POST /api/channels/targets/{surface}/resolve", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.test.send", "category": "channels", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.tools.invoke", "category": "channels", "access": "admin", "rest": "POST /api/channels/tools/{surface}/{toolId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.tools.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/tools", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "channels.tools.surface.list", "category": "channels", "access": "authenticated", "rest": "GET /api/channels/tools/{surface}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkin.config.get", "category": "checkin", "access": "authenticated", "rest": "GET /api/checkin/config", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkin.config.set", "category": "checkin", "access": "admin", "rest": "POST /api/checkin/config", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkin.receipts.list", "category": "checkin", "access": "authenticated", "rest": "GET /api/checkin/receipts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkin.run", "category": "checkin", "access": "authenticated", "rest": "POST /api/checkin/run", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkpoints.create", "category": "checkpoints", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkpoints.diff", "category": "checkpoints", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkpoints.list", "category": "checkpoints", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkpoints.restore", "category": "checkpoints", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkpoints.restorePreview", "category": "checkpoints", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkpoints.revertHunk", "category": "checkpoints", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "checkpoints.revertHunkPreview", "category": "checkpoints", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "ci.status", "category": "ci", "access": "authenticated", "rest": "POST /api/ci/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "ci.watches.create", "category": "ci", "access": "authenticated", "rest": "POST /api/ci/watches", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "ci.watches.delete", "category": "ci", "access": "authenticated", "rest": "DELETE /api/ci/watches/{watchId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "ci.watches.list", "category": "ci", "access": "authenticated", "rest": "GET /api/ci/watches", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "ci.watches.run", "category": "ci", "access": "authenticated", "rest": "POST /api/ci/watches/{watchId}/run", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.events.stream", "category": "companion", "access": "authenticated", "rest": "GET /api/companion/chat/sessions/{sessionId}/events", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.messages.create", "category": "companion", "access": "authenticated", "rest": "POST /api/companion/chat/sessions/{sessionId}/messages", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.messages.edit", "category": "companion", "access": "authenticated", "rest": "POST /api/companion/chat/sessions/{sessionId}/messages/edit", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.messages.list", "category": "companion", "access": "authenticated", "rest": "GET /api/companion/chat/sessions/{sessionId}/messages", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.messages.retry", "category": "companion", "access": "authenticated", "rest": "POST /api/companion/chat/sessions/{sessionId}/messages/retry", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.messages.steer", "category": "companion", "access": "authenticated", "rest": "POST /api/companion/chat/sessions/{sessionId}/messages/steer", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.sessions.close", "category": "companion", "access": "authenticated", "rest": "POST /api/companion/chat/sessions/{sessionId}/close", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.sessions.create", "category": "companion", "access": "authenticated", "rest": "POST /api/companion/chat/sessions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.sessions.delete", "category": "companion", "access": "authenticated", "rest": "DELETE /api/companion/chat/sessions/{sessionId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.sessions.get", "category": "companion", "access": "authenticated", "rest": "GET /api/companion/chat/sessions/{sessionId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.sessions.list", "category": "companion", "access": "authenticated", "rest": "GET /api/companion/chat/sessions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.sessions.update", "category": "companion", "access": "authenticated", "rest": "PATCH /api/companion/chat/sessions/{sessionId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "companion.chat.turns.cancel", "category": "companion", "access": "authenticated", "rest": "POST /api/companion/chat/sessions/{sessionId}/turns/cancel", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "config.get", "category": "config", "access": "admin", "rest": "GET /config", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "config.set", "category": "config", "access": "admin", "rest": "POST /config", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "credentials.delete", "category": "config", "access": "admin", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "credentials.get", "category": "config", "access": "admin", "rest": "GET /config/credentials", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "credentials.set", "category": "config", "access": "admin", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "continuity.snapshot", "category": "continuity", "access": "authenticated", "rest": "GET /api/continuity", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.auth.current", "category": "control-plane", "access": "public", "rest": "GET /api/control-plane/auth", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.auth.login", "category": "control-plane", "access": "public", "rest": "POST /login", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.clients.list", "category": "control-plane", "access": "authenticated", "rest": "GET /api/control-plane/clients", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.contract", "category": "control-plane", "access": "authenticated", "rest": "GET /api/control-plane/contract", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.events.catalog", "category": "control-plane", "access": "authenticated", "rest": "GET /api/control-plane/events/catalog", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.events.stream", "category": "control-plane", "access": "authenticated", "rest": "GET /api/control-plane/events", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.messages.list", "category": "control-plane", "access": "authenticated", "rest": "GET /api/control-plane/messages", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.methods.get", "category": "control-plane", "access": "authenticated", "rest": "GET /api/control-plane/methods/{methodId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.methods.list", "category": "control-plane", "access": "authenticated", "rest": "GET /api/control-plane/methods", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.snapshot", "category": "control-plane", "access": "authenticated", "rest": "GET /api/control-plane", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.status", "category": "control-plane", "access": "authenticated", "rest": "GET /status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "control.web", "category": "control-plane", "access": "authenticated", "rest": "GET /api/control-plane/web", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "relay.pairing.mint", "category": "control-plane", "access": "admin", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "relay.reachability.get", "category": "control-plane", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "update.check", "category": "control-plane", "access": "admin", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "update.status", "category": "control-plane", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "cost.attribution.get", "category": "cost", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "deliveries.get", "category": "deliveries", "access": "authenticated", "rest": "GET /api/deliveries/{deliveryId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "deliveries.list", "category": "deliveries", "access": "authenticated", "rest": "GET /api/deliveries", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "email.draft.create", "category": "email", "access": "admin", "rest": "POST /api/email/drafts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "email.expectation.cancel", "category": "email", "access": "admin", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "email.expectation.list", "category": "email", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "email.expectation.open", "category": "email", "access": "admin", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "email.inbound.status", "category": "email", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "email.inbox.list", "category": "email", "access": "authenticated", "rest": "GET /api/email/inbox", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "email.inbox.read", "category": "email", "access": "authenticated", "rest": "GET /api/email/inbox/{uid}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "email.send", "category": "email", "access": "admin", "rest": "POST /api/email/send", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "flags.graduation.report", "category": "flags", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.archive", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.archived.list", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.archiveFinished", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.attempts.judge", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.attempts.list", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.attempts.pick", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.conflicts.list", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.conflicts.resolve", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.graph.get", "category": "fleet", "access": "authenticated", "rest": "GET /api/fleet/workstreams/{workstreamId}/graph", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.list", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.observed.steer", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.snapshot", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "fleet.unarchive", "category": "fleet", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "health.snapshot", "category": "health", "access": "authenticated", "rest": "GET /api/health", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "ops.memory.get", "category": "health", "access": "authenticated", "rest": "GET /api/ops/memory", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "power.keepAwake.set", "category": "health", "access": "authenticated", "rest": "POST /api/power/keep-awake", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "power.status.get", "category": "health", "access": "authenticated", "rest": "GET /api/power/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.local.install", "category": "health", "access": "authenticated", "rest": "POST /api/voice/local/install", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.local.status", "category": "health", "access": "authenticated", "rest": "GET /api/voice/local/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.wake.model.get", "category": "health", "access": "authenticated", "rest": "GET /api/voice/wake/model", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.wake.provision", "category": "health", "access": "authenticated", "rest": "POST /api/voice/wake/provision", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.wake.status", "category": "health", "access": "authenticated", "rest": "GET /api/voice/wake/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "intelligence.snapshot", "category": "intelligence", "access": "authenticated", "rest": "GET /api/intelligence", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.askHomeGraph", "category": "knowledge", "access": "authenticated", "rest": "POST /api/homeassistant/home-graph/ask", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.browse", "category": "knowledge", "access": "authenticated", "rest": "GET /api/homeassistant/home-graph/browse", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.export", "category": "knowledge", "access": "authenticated", "rest": "POST /api/homeassistant/home-graph/export", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.generateHomeGraphPacket", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/packet", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.generateRoomPage", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/room-page", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.import", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/import", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.ingestHomeGraphArtifact", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/ingest/artifact", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.ingestHomeGraphNote", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/ingest/note", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.ingestHomeGraphUrl", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/ingest/url", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.linkHomeGraphKnowledge", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/link", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.listHomeGraphIssues", "category": "knowledge", "access": "authenticated", "rest": "GET /api/homeassistant/home-graph/issues", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.map", "category": "knowledge", "access": "authenticated", "rest": "POST /api/homeassistant/home-graph/map", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.pages.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/homeassistant/home-graph/pages", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.refinement.run", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/refinement/run", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.refinement.task.cancel", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/refinement/tasks/{id}/cancel", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.refinement.task.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/homeassistant/home-graph/refinement/tasks/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.refinement.tasks.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/homeassistant/home-graph/refinement/tasks", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.refreshDevicePassport", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/device-passport", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.reindex", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/reindex", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.reset", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/reset", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.reviewHomeGraphFact", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/facts/review", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.sources.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/homeassistant/home-graph/sources", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.status", "category": "knowledge", "access": "authenticated", "rest": "GET /api/homeassistant/home-graph/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.syncHomeGraph", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/sync", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "homeassistant.homeGraph.unlinkHomeGraphKnowledge", "category": "knowledge", "access": "admin", "rest": "POST /api/homeassistant/home-graph/unlink", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.ask", "category": "knowledge", "access": "authenticated", "rest": "POST /api/knowledge/ask", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.candidate.decide", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/candidates/{id}/decide", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.candidate.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/candidates/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.candidates.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/candidates", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.connector.doctor", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/connectors/{id}/doctor", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.connector.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/connectors/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.connectors.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/connectors", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.extraction.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/extractions/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.extractions.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/extractions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.graphql.execute", "category": "knowledge", "access": "authenticated", "rest": "POST /api/knowledge/graphql", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.graphql.schema", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/graphql/schema", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.ingest.artifact", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/ingest/artifact", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.ingest.bookmarks", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/ingest/bookmarks", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.ingest.browserHistory", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/ingest/browser-history", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.ingest.connector", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/ingest/connector", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.ingest.url", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/ingest/url", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.ingest.urls", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/ingest/urls", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.issue.review", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/issues/{id}/review", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.issues.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/issues", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.item.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/items/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.job-runs.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/job-runs", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.job.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/jobs/{jobId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.job.run", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/jobs/{jobId}/run", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.jobs.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/jobs", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.lint", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/lint", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.map", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/map", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.nodes.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/nodes", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.packet", "category": "knowledge", "access": "authenticated", "rest": "POST /api/knowledge/packet", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.projection.materialize", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/projections/materialize", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.projection.render", "category": "knowledge", "access": "authenticated", "rest": "POST /api/knowledge/projections/render", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.projections.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/projections", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.refinement.run", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/refinement/run", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.refinement.task.cancel", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/refinement/tasks/{id}/cancel", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.refinement.task.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/refinement/tasks/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.refinement.tasks.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/refinement/tasks", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.reindex", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/reindex", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.report.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/reports/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.reports.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/reports", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.schedule.delete", "category": "knowledge", "access": "admin", "rest": "DELETE /api/knowledge/schedules/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.schedule.enable", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/schedules/{id}/enabled", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.schedule.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/schedules/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.schedule.save", "category": "knowledge", "access": "admin", "rest": "POST /api/knowledge/schedules", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.schedules.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/schedules", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.search", "category": "knowledge", "access": "authenticated", "rest": "POST /api/knowledge/search", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.source.extraction.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/sources/{id}/extraction", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.sources.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/sources", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.status", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "knowledge.usage.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/knowledge/usage", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.decisions.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/projects/planning/decisions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.decisions.record", "category": "knowledge", "access": "admin", "rest": "POST /api/projects/planning/decisions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.evaluate", "category": "knowledge", "access": "authenticated", "rest": "POST /api/projects/planning/evaluate", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.language.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/projects/planning/language", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.language.upsert", "category": "knowledge", "access": "admin", "rest": "POST /api/projects/planning/language", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.state.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/projects/planning/state", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.state.upsert", "category": "knowledge", "access": "admin", "rest": "POST /api/projects/planning/state", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.status", "category": "knowledge", "access": "authenticated", "rest": "GET /api/projects/planning/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.workPlan.clearCompleted", "category": "knowledge", "access": "admin", "rest": "POST /api/projects/planning/work-plan/clear-completed", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.workPlan.snapshot", "category": "knowledge", "access": "authenticated", "rest": "GET /api/projects/planning/work-plan", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.workPlan.task.create", "category": "knowledge", "access": "admin", "rest": "POST /api/projects/planning/work-plan/tasks", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.workPlan.task.delete", "category": "knowledge", "access": "admin", "rest": "DELETE /api/projects/planning/work-plan/tasks/{taskId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.workPlan.task.get", "category": "knowledge", "access": "authenticated", "rest": "GET /api/projects/planning/work-plan/tasks/{taskId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.workPlan.task.status", "category": "knowledge", "access": "admin", "rest": "POST /api/projects/planning/work-plan/tasks/{taskId}/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.workPlan.task.update", "category": "knowledge", "access": "admin", "rest": "PATCH /api/projects/planning/work-plan/tasks/{taskId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.workPlan.tasks.list", "category": "knowledge", "access": "authenticated", "rest": "GET /api/projects/planning/work-plan/tasks", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "projectPlanning.workPlan.tasks.reorder", "category": "knowledge", "access": "admin", "rest": "POST /api/projects/planning/work-plan/tasks/reorder", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "mcp.config.get", "category": "mcp", "access": "authenticated", "rest": "GET /api/mcp/config", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "mcp.config.reload", "category": "mcp", "access": "admin", "rest": "POST /api/mcp/reload", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "mcp.servers.list", "category": "mcp", "access": "authenticated", "rest": "GET /api/mcp/servers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "mcp.servers.remove", "category": "mcp", "access": "admin", "rest": "DELETE /api/mcp/config/servers/{serverName}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "mcp.servers.reveal", "category": "mcp", "access": "admin", "rest": "GET /api/mcp/servers/reveal", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "mcp.servers.upsert", "category": "mcp", "access": "admin", "rest": "POST /api/mcp/config/servers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "mcp.tools.list", "category": "mcp", "access": "authenticated", "rest": "GET /api/mcp/tools", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "media.analyze", "category": "media", "access": "authenticated", "rest": "POST /api/media/analyze", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "media.generate", "category": "media", "access": "authenticated", "rest": "POST /api/media/generate", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "media.providers.list", "category": "media", "access": "authenticated", "rest": "GET /api/media/providers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "media.transform", "category": "media", "access": "authenticated", "rest": "POST /api/media/transform", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "multimodal.analyze", "category": "media", "access": "authenticated", "rest": "POST /api/multimodal/analyze", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "multimodal.packet", "category": "media", "access": "authenticated", "rest": "POST /api/multimodal/packet", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "multimodal.providers.list", "category": "media", "access": "authenticated", "rest": "GET /api/multimodal/providers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "multimodal.status", "category": "media", "access": "authenticated", "rest": "GET /api/multimodal", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "multimodal.writeback", "category": "media", "access": "admin", "rest": "POST /api/multimodal/writeback", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.consolidation.receipts", "category": "memory", "access": "authenticated", "rest": "GET /api/memory/consolidation/receipts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.doctor", "category": "memory", "access": "authenticated", "rest": "GET /api/memory/doctor", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.embeddings.default.set", "category": "memory", "access": "admin", "rest": "POST /api/memory/embeddings/default", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.projections.get", "category": "memory", "access": "authenticated", "rest": "GET /api/memory/projections/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.projections.list", "category": "memory", "access": "authenticated", "rest": "GET /api/memory/projections", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.add", "category": "memory", "access": "authenticated", "rest": "POST /api/memory/records", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.delete", "category": "memory", "access": "authenticated", "rest": "DELETE /api/memory/records/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.export", "category": "memory", "access": "authenticated", "rest": "POST /api/memory/records/export", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.get", "category": "memory", "access": "authenticated", "rest": "GET /api/memory/records/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.import", "category": "memory", "access": "authenticated", "rest": "POST /api/memory/records/import", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.links.add", "category": "memory", "access": "authenticated", "rest": "POST /api/memory/records/{id}/links", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.links.list", "category": "memory", "access": "authenticated", "rest": "GET /api/memory/records/{id}/links", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.list", "category": "memory", "access": "authenticated", "rest": "POST /api/memory/records/list", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.search", "category": "memory", "access": "authenticated", "rest": "POST /api/memory/records/search", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.search-semantic", "category": "memory", "access": "authenticated", "rest": "POST /api/memory/records/search-semantic", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.update", "category": "memory", "access": "authenticated", "rest": "POST /api/memory/records/{id}/update", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.records.update-review", "category": "memory", "access": "authenticated", "rest": "POST /api/memory/records/{id}/review", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.review-queue", "category": "memory", "access": "authenticated", "rest": "GET /api/memory/review-queue", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.vector.rebuild", "category": "memory", "access": "admin", "rest": "POST /api/memory/vector/rebuild", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "memory.vector.stats", "category": "memory", "access": "authenticated", "rest": "GET /api/memory/vector", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.acknowledge", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/acknowledge", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.answer", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/answer", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.confirm", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/confirm", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.conflict.resolve", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/conflict/resolve", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.gifts", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/gifts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.interview.answer", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/interview/answer", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.interview.get", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/interview", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.interview.record", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/interview/record", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.list", "category": "occasions", "access": "authenticated", "rest": "GET /api/occasions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.pending", "category": "occasions", "access": "authenticated", "rest": "GET /api/occasions/pending", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.plans.confirm", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/plans/confirm", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.plans.list", "category": "occasions", "access": "authenticated", "rest": "GET /api/occasions/plans", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.plans.propose", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/plans/propose", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.propose", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/propose", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.remove", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/remove", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.state", "category": "occasions", "access": "authenticated", "rest": "GET /api/occasions/state", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "occasions.sweep", "category": "occasions", "access": "authenticated", "rest": "POST /api/occasions/sweep", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "pairing.handoff.complete", "category": "pairing", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "pairing.handoff.create", "category": "pairing", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "pairing.posture.get", "category": "pairing", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "pairing.tokens.create", "category": "pairing", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "pairing.tokens.delete", "category": "pairing", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "pairing.tokens.list", "category": "pairing", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "schema-less", "outputSchemaCoverage": "typed" }, { "id": "pairing.tokens.migrate", "category": "pairing", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "pairing.tokens.rename", "category": "pairing", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "pairing.tokens.revokeShared", "category": "pairing", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "schema-less", "outputSchemaCoverage": "typed" }, { "id": "panels.list", "category": "panels", "access": "authenticated", "rest": "GET /api/panels", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "panels.open", "category": "panels", "access": "authenticated", "rest": "POST /api/panels/open", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "payments.budget.status", "category": "payments", "access": "authenticated", "rest": "GET /api/payments/budget", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "payments.cards.create", "category": "payments", "access": "admin", "rest": "POST /api/payments/cards", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "payments.cards.delete", "category": "payments", "access": "admin", "rest": "DELETE /api/payments/cards/{id}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "payments.cards.list", "category": "payments", "access": "authenticated", "rest": "GET /api/payments/cards", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "payments.checkout.begin", "category": "payments", "access": "admin", "rest": "POST /api/payments/checkout/begin", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "payments.checkout.fillCard", "category": "payments", "access": "admin", "rest": "POST /api/payments/checkout/fill-card", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "payments.purchases.list", "category": "payments", "access": "authenticated", "rest": "GET /api/payments/purchases", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "permissions.rules.delete", "category": "permissions", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "permissions.rules.list", "category": "permissions", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "principals.create", "category": "principals", "access": "authenticated", "rest": "POST /api/principals", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "principals.delete", "category": "principals", "access": "authenticated", "rest": "DELETE /api/principals/{principalId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "principals.get", "category": "principals", "access": "authenticated", "rest": "GET /api/principals/{principalId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "principals.list", "category": "principals", "access": "authenticated", "rest": "GET /api/principals", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "principals.resolve", "category": "principals", "access": "authenticated", "rest": "POST /api/principals/resolve", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "principals.update", "category": "principals", "access": "authenticated", "rest": "POST /api/principals/{principalId}/update", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "profile.append", "category": "profile", "access": "authenticated", "rest": "POST /api/profile/append", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "profile.forget", "category": "profile", "access": "authenticated", "rest": "POST /api/profile/forget", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "profile.get", "category": "profile", "access": "authenticated", "rest": "GET /api/profile/fields/{fieldId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "profile.person", "category": "profile", "access": "authenticated", "rest": "POST /api/profile/person", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "profile.provenance", "category": "profile", "access": "authenticated", "rest": "GET /api/profile/fields/{fieldId}/provenance", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "profile.read", "category": "profile", "access": "authenticated", "rest": "GET /api/profile", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "profile.set", "category": "profile", "access": "authenticated", "rest": "POST /api/profile/set", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "profile.status", "category": "profile", "access": "authenticated", "rest": "GET /api/profile/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "profile.undo", "category": "profile", "access": "authenticated", "rest": "POST /api/profile/undo", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "models.current.get", "category": "providers", "access": "authenticated", "rest": "GET /api/models/current", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "models.current.set", "category": "providers", "access": "authenticated", "rest": "PATCH /api/models/current", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "models.list", "category": "providers", "access": "authenticated", "rest": "GET /api/models", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "providers.get", "category": "providers", "access": "authenticated", "rest": "GET /api/providers/{providerId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "providers.list", "category": "providers", "access": "authenticated", "rest": "GET /api/providers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "providers.usage.get", "category": "providers", "access": "authenticated", "rest": "GET /api/providers/{providerId}/usage", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "push.subscriptions.create", "category": "push", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "push.subscriptions.delete", "category": "push", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "push.subscriptions.list", "category": "push", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "schema-less", "outputSchemaCoverage": "typed" }, { "id": "push.subscriptions.reconcile", "category": "push", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "push.subscriptions.verify", "category": "push", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "push.vapid.get", "category": "push", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "schema-less", "outputSchemaCoverage": "typed" }, { "id": "quota.fanout.get", "category": "quota", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "quota.snapshot.get", "category": "quota", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "stepup.challenge.mint", "category": "relay", "access": "authenticated", "rest": "POST /api/stepup/challenge", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "stepup.credentials.register", "category": "relay", "access": "admin", "rest": "POST /api/stepup/credentials", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.node_host.contract", "category": "remote", "access": "authenticated", "rest": "GET /api/remote/node-host/contract", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.pair.requests.approve", "category": "remote", "access": "admin", "rest": "POST /api/remote/pair/requests/{requestId}/approve", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.pair.requests.list", "category": "remote", "access": "authenticated", "rest": "GET /api/remote/pair/requests", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.pair.requests.reject", "category": "remote", "access": "admin", "rest": "POST /api/remote/pair/requests/{requestId}/reject", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.peers.disconnect", "category": "remote", "access": "admin", "rest": "POST /api/remote/peers/{peerId}/disconnect", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.peers.invoke", "category": "remote", "access": "admin", "rest": "POST /api/remote/peers/{peerId}/invoke", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.peers.list", "category": "remote", "access": "authenticated", "rest": "GET /api/remote/peers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.peers.token.revoke", "category": "remote", "access": "admin", "rest": "POST /api/remote/peers/{peerId}/token/revoke", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.peers.token.rotate", "category": "remote", "access": "admin", "rest": "POST /api/remote/peers/{peerId}/token/rotate", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.snapshot", "category": "remote", "access": "authenticated", "rest": "GET /api/remote", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.work.cancel", "category": "remote", "access": "admin", "rest": "POST /api/remote/work/{workId}/cancel", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "remote.work.list", "category": "remote", "access": "authenticated", "rest": "GET /api/remote/work", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "tailscale.get", "category": "remote-access", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "schema-less", "outputSchemaCoverage": "typed" }, { "id": "tailscale.serve.run", "category": "remote-access", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "schema-less", "outputSchemaCoverage": "typed" }, { "id": "review.snapshot", "category": "review", "access": "authenticated", "rest": "GET /api/review", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "rewind.apply", "category": "rewind", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "rewind.conversation.host.register", "category": "rewind", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "rewind.conversation.host.release", "category": "rewind", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "rewind.conversation.hosts.list", "category": "rewind", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "rewind.conversation.requests.answer", "category": "rewind", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "rewind.conversation.requests.take", "category": "rewind", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "rewind.plan", "category": "rewind", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "routes.bindings.create", "category": "routes", "access": "admin", "rest": "POST /api/routes/bindings", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "routes.bindings.delete", "category": "routes", "access": "admin", "rest": "DELETE /api/routes/bindings/{bindingId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "routes.bindings.list", "category": "routes", "access": "authenticated", "rest": "GET /api/routes/bindings", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "routes.bindings.update", "category": "routes", "access": "admin", "rest": "PATCH /api/routes/bindings/{bindingId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "routes.snapshot", "category": "routes", "access": "authenticated", "rest": "GET /api/routes", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "surfaces.list", "category": "routes", "access": "authenticated", "rest": "GET /api/surfaces", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "devices.artifacts.list", "category": "runtime", "access": "authenticated", "rest": "GET /api/devices/artifacts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "devices.artifacts.read", "category": "runtime", "access": "authenticated", "rest": "GET /api/devices/artifacts/{artifactId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "devices.capability.request", "category": "runtime", "access": "authenticated", "rest": "POST /api/devices/capability/request", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "devices.grants.list", "category": "runtime", "access": "authenticated", "rest": "GET /api/devices/grants", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "devices.grants.revoke", "category": "runtime", "access": "authenticated", "rest": "POST /api/devices/grants/revoke", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "devices.housekeeping.run", "category": "runtime", "access": "authenticated", "rest": "POST /api/devices/housekeeping", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "devices.nodes.list", "category": "runtime", "access": "authenticated", "rest": "GET /api/devices/nodes", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "runtime.metrics.get", "category": "runtime", "access": "authenticated", "rest": "GET /api/runtime/metrics", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "scheduler.capacity", "category": "scheduler", "access": "authenticated", "rest": "GET /api/runtime/scheduler", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "services.install", "category": "services", "access": "admin", "rest": "POST /api/service/install", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "services.restart", "category": "services", "access": "admin", "rest": "POST /api/service/restart", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "services.start", "category": "services", "access": "admin", "rest": "POST /api/service/start", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "services.status", "category": "services", "access": "authenticated", "rest": "GET /api/service/status", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "services.stop", "category": "services", "access": "admin", "rest": "POST /api/service/stop", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "services.uninstall", "category": "services", "access": "admin", "rest": "POST /api/service/uninstall", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.changes.get", "category": "sessions", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.close", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/close", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.contextUsage.get", "category": "sessions", "access": "authenticated", "rest": "GET /api/sessions/{sessionId}/context-usage", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.create", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.delete", "category": "sessions", "access": "authenticated", "rest": "DELETE /api/sessions/{sessionId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.detach", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/detach", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.followUp", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/follow-up", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.get", "category": "sessions", "access": "authenticated", "rest": "GET /api/sessions/{sessionId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.hosted.attach", "category": "sessions", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.hosted.create", "category": "sessions", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.hosted.detach", "category": "sessions", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.hosted.kill", "category": "sessions", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.hosted.list", "category": "sessions", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.inputs.cancel", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/inputs/{inputId}/cancel", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.inputs.deliver", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/inputs/{inputId}/deliver", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.inputs.list", "category": "sessions", "access": "authenticated", "rest": "GET /api/sessions/{sessionId}/inputs", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.integration.snapshot", "category": "sessions", "access": "authenticated", "rest": "GET /api/session", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.list", "category": "sessions", "access": "authenticated", "rest": "GET /api/sessions", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.messages.create", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/messages", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.messages.list", "category": "sessions", "access": "authenticated", "rest": "GET /api/sessions/{sessionId}/messages", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.permissionMode.get", "category": "sessions", "access": "authenticated", "rest": "GET /api/sessions/{sessionId}/permission-mode", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.permissionMode.set", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/permission-mode", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.queuedMessages.delete", "category": "sessions", "access": "authenticated", "rest": "DELETE /api/sessions/{sessionId}/queued-messages/{messageId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.queuedMessages.edit", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/queued-messages/{messageId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.queuedMessages.list", "category": "sessions", "access": "authenticated", "rest": "GET /api/sessions/{sessionId}/queued-messages", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.register", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/register", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.reopen", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/reopen", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.search", "category": "sessions", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.steer", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/steer", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "sessions.toolCalls.cancel", "category": "sessions", "access": "authenticated", "rest": "POST /api/sessions/{sessionId}/tool-calls/{callId}/cancel", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "security.settings", "category": "settings", "access": "authenticated", "rest": "GET /api/security-settings", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "settings.snapshot", "category": "settings", "access": "authenticated", "rest": "GET /api/settings", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "skills.create", "category": "skills", "access": "authenticated", "rest": "POST /api/skills", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "skills.delete", "category": "skills", "access": "authenticated", "rest": "DELETE /api/skills/{name}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "skills.get", "category": "skills", "access": "authenticated", "rest": "GET /api/skills/{name}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "skills.list", "category": "skills", "access": "authenticated", "rest": "GET /api/skills", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "skills.update", "category": "skills", "access": "authenticated", "rest": "POST /api/skills/{name}/update", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "tasks.cancel", "category": "tasks", "access": "authenticated", "rest": "POST /api/tasks/{taskId}/cancel", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "tasks.create", "category": "tasks", "access": "authenticated", "rest": "POST /task", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "tasks.get", "category": "tasks", "access": "authenticated", "rest": "GET /api/tasks/{taskId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "tasks.list", "category": "tasks", "access": "authenticated", "rest": "GET /api/tasks", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "tasks.retry", "category": "tasks", "access": "authenticated", "rest": "POST /api/tasks/{taskId}/retry", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "tasks.status", "category": "tasks", "access": "authenticated", "rest": "GET /task/{agentId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "telemetry.errors.list", "category": "telemetry", "access": "authenticated", "rest": "GET /api/v1/telemetry/errors", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "telemetry.events.list", "category": "telemetry", "access": "authenticated", "rest": "GET /api/v1/telemetry/events", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "telemetry.metrics.get", "category": "telemetry", "access": "authenticated", "rest": "GET /api/v1/telemetry/metrics", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "telemetry.otlp.logs", "category": "telemetry", "access": "authenticated", "rest": "GET /api/v1/telemetry/otlp/v1/logs", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "telemetry.otlp.metrics", "category": "telemetry", "access": "authenticated", "rest": "GET /api/v1/telemetry/otlp/v1/metrics", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "telemetry.otlp.traces", "category": "telemetry", "access": "authenticated", "rest": "GET /api/v1/telemetry/otlp/v1/traces", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "telemetry.snapshot", "category": "telemetry", "access": "authenticated", "rest": "GET /api/v1/telemetry", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "telemetry.stream", "category": "telemetry", "access": "authenticated", "rest": "GET /api/v1/telemetry/stream", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "telemetry.traces.list", "category": "telemetry", "access": "authenticated", "rest": "GET /api/v1/telemetry/traces", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.providers.list", "category": "voice", "access": "authenticated", "rest": "GET /api/voice/providers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.realtime.session", "category": "voice", "access": "authenticated", "rest": "POST /api/voice/realtime/session", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.status", "category": "voice", "access": "authenticated", "rest": "GET /api/voice", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.stt", "category": "voice", "access": "authenticated", "rest": "POST /api/voice/stt", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.tts", "category": "voice", "access": "authenticated", "rest": "POST /api/voice/tts", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.tts.stream", "category": "voice", "access": "authenticated", "rest": "POST /api/voice/tts/stream", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "voice.voices.list", "category": "voice", "access": "authenticated", "rest": "GET /api/voice/voices", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "watchers.create", "category": "watchers", "access": "admin", "rest": "POST /api/watchers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "watchers.delete", "category": "watchers", "access": "admin", "rest": "DELETE /api/watchers/{watcherId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "watchers.list", "category": "watchers", "access": "authenticated", "rest": "GET /api/watchers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "watchers.run", "category": "watchers", "access": "admin", "rest": "POST /api/watchers/{watcherId}/run", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "watchers.start", "category": "watchers", "access": "admin", "rest": "POST /api/watchers/{watcherId}/start", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "watchers.stop", "category": "watchers", "access": "admin", "rest": "POST /api/watchers/{watcherId}/stop", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "watchers.update", "category": "watchers", "access": "admin", "rest": "PATCH /api/watchers/{watcherId}", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "web_search.providers.list", "category": "web-search", "access": "authenticated", "rest": "GET /api/web-search/providers", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "web_search.query", "category": "web-search", "access": "authenticated", "rest": "POST /api/web-search/query", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "workspaces.registrations.add", "category": "workspaces", "access": "authenticated", "rest": "POST /api/workspaces/registrations", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "workspaces.registrations.list", "category": "workspaces", "access": "authenticated", "rest": "GET /api/workspaces/registrations", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "workspaces.registrations.remove", "category": "workspaces", "access": "authenticated", "rest": "DELETE /api/workspaces/registrations", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "workspaces.resolve", "category": "workspaces", "access": "authenticated", "rest": "POST /api/workspaces/resolve", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "worktrees.discard", "category": "worktrees", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "worktrees.setup.run", "category": "worktrees", "access": "authenticated", "rest": null, "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" }, { "id": "worktrees.snapshot", "category": "worktrees", "access": "authenticated", "rest": "GET /api/worktrees", "typedClientIo": true, "inputSchemaCoverage": "typed", "outputSchemaCoverage": "typed" } ] }