{ "openapi": "3.1.0", "info": { "title": "Snaga — AGI Ready", "version": "0.1.0", "description": "API for managing AI agents, runs, sessions, and supporting infrastructure.", "license": { "name": "MIT" } }, "servers": [ { "url": "https://api.snaga.ai", "description": "Production" }, { "url": "http://localhost:8080", "description": "Local development" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "snaga__", "description": "API key in format: snaga__" } }, "schemas": { "Error": { "type": "object", "description": "RFC 9457 problem+json style error; correlationId for request tracing.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "correlationId": { "type": "string", "description": "Request ID for tracing" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } }, "description": "Field-level validation errors (present on 422 responses)" } }, "required": [ "type", "title", "status" ] }, "Agent": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "model": { "$ref": "#/components/schemas/AgentModelConfig" }, "prompts": { "type": "object", "properties": { "system": { "type": "string" }, "developer": { "type": "string" } } }, "mcp": { "type": "object" }, "policies": { "type": "object" }, "skills": { "type": "array", "items": { "type": "object" } }, "thinking": { "type": [ "object", "null" ] }, "effort_policy": { "type": [ "object", "null" ] }, "resource_limits": { "type": [ "object", "null" ] }, "memory": { "type": [ "object", "null" ] }, "guardrails": { "type": [ "object", "null" ] }, "approval_required_tools": { "type": "array", "items": { "type": "string" }, "description": "Tool names requiring human approval before execution" }, "built_in_tools": { "type": "array", "items": { "type": "string" }, "description": "Built-in tool names enabled for this agent" }, "image_generation": { "type": [ "object", "null" ], "description": "Image generation configuration" }, "knowledge_base_id": { "type": [ "string", "null" ], "description": "Linked knowledge base ID" }, "fallback_model": { "type": [ "object", "null" ], "description": "Fallback model configuration" }, "execution_mode": { "type": "string", "enum": [ "async", "worker" ] }, "worker_reuse": { "type": "boolean" }, "schedule": { "type": [ "object", "null" ], "description": "Cron schedule configuration" }, "a2a": { "type": [ "object", "null" ], "description": "Agent-to-Agent protocol configuration" }, "risk_classification": { "type": [ "object", "null" ], "description": "EU AI Act risk classification" }, "workspace_id": { "type": [ "string", "null" ], "description": "Workspace this agent belongs to" }, "context_strategy": { "type": "string", "enum": [ "compaction", "summarize", "truncate", "sliding_window" ] }, "context_window_size": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "agent_id", "tenant_id", "name", "model", "created_at" ] }, "AgentModelConfig": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai_compat", "anthropic", "hf", "deepseek", "openai", "claude", "custom" ] }, "model_ref": { "type": "string" }, "endpoint_url": { "type": "string", "format": "uri" }, "api_key_ref": { "type": "string" }, "capabilities": { "type": "object" } }, "required": [ "provider", "model_ref", "capabilities" ] }, "Run": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "timeout", "guardrail_blocked", "paused", "awaiting_approval", "auth_required", "rejected" ] }, "input": { "type": "object" }, "output": { "type": [ "object", "null" ] }, "metrics": { "$ref": "#/components/schemas/RunMetrics" }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "team_run_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Team run ID if part of a team execution" }, "metadata": { "type": "object", "additionalProperties": true, "description": "User-supplied metadata" }, "step_seq": { "type": "integer", "description": "Current step sequence number" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" }, "description": "Run artifacts" }, "resource_limits": { "type": "object", "properties": { "max_duration_ms": { "type": "integer" }, "max_steps": { "type": "integer" }, "max_tool_calls": { "type": "integer" }, "max_tokens_per_run": { "type": "integer" } }, "description": "Resource limits for the run" } }, "required": [ "run_id", "tenant_id", "agent_id", "status", "created_at" ] }, "RunMetrics": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "steps_count": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "thinking_tokens": { "type": "integer" }, "tool_calls_count": { "type": "integer" }, "llm_calls_count": { "type": "integer" }, "guardrail_checks": { "type": "integer" }, "guardrail_violations": { "type": "integer" }, "memory_retrievals": { "type": "integer" }, "memory_extractions": { "type": "integer" }, "total_cost_usd": { "type": [ "number", "null" ], "description": "Estimated total cost in USD" } } }, "Artifact": { "type": "object", "required": [ "artifact_id", "run_id", "name", "mime_type", "size_bytes", "created_at" ], "properties": { "artifact_id": { "type": "string", "format": "uuid" }, "run_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "storage_ref": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "Session": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "closed", "expired" ] }, "conversation_history": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationEntry" } }, "metadata": { "type": "object" }, "runs": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "team_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Team ID if session belongs to a team" }, "branches": { "type": "array", "items": { "type": "object" }, "description": "Session branches for conversation forking" }, "active_branch": { "type": "string", "description": "Currently active branch ID" }, "queue_mode": { "type": "string", "enum": [ "allow", "reject" ], "description": "How to handle concurrent runs in this session" } }, "required": [ "session_id", "tenant_id", "agent_id", "status" ] }, "ConversationEntry": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system", "tool_result" ] }, "content": { "type": "string", "description": "Message content" }, "run_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "compacted": { "type": "boolean" } } }, "MemoryEntry": { "type": "object", "properties": { "entry_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "episodic", "semantic", "procedural", "note" ] }, "content": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "relevance_score": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "source_run_id": { "type": "string" } }, "required": [ "entry_id", "content" ] }, "WebhookSubscription": { "type": "object", "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled", "failing" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "webhook_id", "url", "events", "status" ] }, "ApiKeyResponse": { "type": "object", "properties": { "key_id": { "type": "string" }, "prefix": { "type": "string" }, "raw_key": { "type": "string", "description": "Shown once. Save immediately." }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "warning": { "type": "string" } } }, "Tenant": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended", "trial" ] }, "plan": { "type": "string", "enum": [ "free", "starter", "pro", "enterprise" ] }, "quotas": { "type": "object" }, "settings": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "IntegrationCatalogItem": { "type": "object", "description": "Available integration (connector) type in the catalog", "properties": { "id": { "type": "string", "description": "Connector id (e.g. github, stripe, notion, slack)" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "auth_type": { "type": "string", "enum": [ "api_key", "oauth2", "webhook", "none" ] }, "config_schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string" }, "required": { "type": "boolean" }, "description": { "type": "string" } } } } }, "required": [ "id", "name", "auth_type" ] }, "AgentIntegration": { "type": "object", "description": "Agent-scoped integration (connection) instance", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string" }, "connector_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "error" ] }, "config": { "type": "object", "description": "Redacted config (no secrets)" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agent_id", "connector_id", "name", "status" ] }, "OAuthStartResponse": { "type": "object", "description": "Response for starting OAuth flow", "properties": { "auth_url": { "type": "string", "format": "uri" }, "state": { "type": "string" } }, "required": [ "auth_url", "state" ] }, "OAuthCompleteRequest": { "type": "object", "description": "Body to complete OAuth after callback", "properties": { "state": { "type": "string" }, "code": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Display name for this connection" } }, "required": [ "state", "code", "agent_id" ] }, "AuthVerifyCodeRequest": { "type": "object", "description": "Body for POST /api/v1/auth/verify-code. No request_id; code is bound to email only.", "properties": { "email": { "type": "string", "format": "email", "description": "Same email used in request-code" }, "code": { "type": "string", "minLength": 4, "description": "OTP from email (6 digits); spaces are stripped server-side" } }, "required": [ "email", "code" ] }, "AuthVerifyCodeResponse": { "type": "object", "description": "Success response: API key to use as Bearer token", "properties": { "api_key": { "type": "string", "description": "snaga__; store and use as Authorization: Bearer " } }, "required": [ "api_key" ] }, "RunStep": { "type": "object", "properties": { "step_id": { "type": "string", "format": "uuid" }, "run_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string" }, "step_index": { "type": "integer" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "metrics": { "$ref": "#/components/schemas/RunStepMetrics" }, "tool_calls": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" } } }, "RunStepMetrics": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "thinking_tokens": { "type": "integer" }, "llm_calls": { "type": "integer" }, "tool_calls_count": { "type": "integer" }, "cost_usd": { "type": "number" } } }, "CoreMemoryBlock": { "type": "object", "properties": { "block_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "tenant_id": { "type": "string" }, "label": { "type": "string" }, "content": { "type": "string" }, "max_tokens": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Experiment": { "type": "object", "properties": { "experiment_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string" }, "agent_id": { "type": "string" }, "name": { "type": "string" }, "dataset_id": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "eval_run_id": { "type": "string" } } } }, "status": { "type": "string", "enum": [ "pending", "running", "completed" ] }, "comparison": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } } }, "responses": { "Unauthorized": { "description": "Authentication required or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Insufficient permissions or quota exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until rate limit resets" }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "LengthRequired": { "description": "Content-Length header required for application/json requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "Request body exceeds size limit", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for idempotent request. Duplicate requests with the same key within 24 h return the cached response.", "schema": { "type": "string", "format": "uuid" } } } }, "paths": { "/health": { "get": { "operationId": "getHealth", "summary": "Health check", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Server is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ready": { "get": { "operationId": "getReady", "summary": "Readiness probe (checks KV connectivity)", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Server is ready to accept requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "not_ready" ] }, "timestamp": { "type": "string", "format": "date-time" }, "checks": { "type": "object", "properties": { "kv": { "type": "string" } } } } } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Server is not ready" } } } }, "/metrics": { "get": { "operationId": "getMetrics", "summary": "Prometheus-compatible metrics export", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Prometheus text format metrics", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bootstrap": { "post": { "operationId": "bootstrap", "summary": "Bootstrap the platform (first-time setup)", "tags": [ "Bootstrap" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_name": { "type": "string", "default": "Admin Tenant" }, "tenant_slug": { "type": "string", "default": "admin" } } } } } }, "responses": { "201": { "description": "Platform bootstrapped" }, "409": { "description": "Already bootstrapped", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents": { "post": { "operationId": "createAgent", "summary": "Create an agent", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "model" ], "properties": { "name": { "type": "string" }, "model": { "$ref": "#/components/schemas/AgentModelConfig" }, "description": { "type": "string" }, "prompts": { "type": "object" }, "skills": { "type": "array" }, "thinking": { "type": "object" }, "resource_limits": { "type": "object" }, "memory": { "type": "object" }, "guardrails": { "type": "object" } } } } } }, "responses": { "201": { "description": "Agent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "411": { "$ref": "#/components/responses/LengthRequired", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listAgents", "summary": "List all agents", "tags": [ "Agents" ], "parameters": [ { "name": "workspace_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by workspace" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Agent list", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "total": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getAgent", "summary": "Get an agent", "tags": [ "Agents" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } }, "description": "Successful response" }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updateAgent", "summary": "Update an agent", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } }, "description": "Successful response" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAgent", "summary": "Delete an agent", "tags": [ "Agents" ], "responses": { "200": { "description": "Agent deleted" }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/integrations/catalog": { "get": { "operationId": "listIntegrationsCatalog", "summary": "List available integration types (connectors)", "tags": [ "Integrations" ], "responses": { "200": { "description": "Catalog of available connectors", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationCatalogItem" } } } } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/integrations/{provider}/oauth/start": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github", "stripe", "notion", "slack", "x_twitter", "linkedin", "youtube", "instagram" ] } } ], "post": { "operationId": "startOAuth", "summary": "Start OAuth flow for an integration provider", "tags": [ "Integrations" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Redirect URL and state for OAuth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthStartResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/integrations/{provider}/oauth/callback": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github", "stripe", "notion", "slack", "x_twitter", "linkedin", "youtube", "instagram" ] } } ], "get": { "operationId": "oauthCallback", "summary": "OAuth callback (redirect from provider); returns HTML that posts to complete", "tags": [ "Integrations" ], "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to app with state/code" }, "400": { "description": "Missing code or state", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/integrations/{provider}/oauth/complete": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github", "stripe", "notion", "slack", "x_twitter", "linkedin", "youtube", "instagram" ] } } ], "post": { "operationId": "completeOAuth", "summary": "Complete OAuth after callback (exchange code for tokens, create connection)", "tags": [ "Integrations" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthCompleteRequest" } } } }, "responses": { "200": { "description": "Integration created and linked to agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentIntegration" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/integrations": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listAgentIntegrations", "summary": "List integrations for an agent", "tags": [ "Integrations" ], "responses": { "200": { "description": "List of agent-scoped integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/AgentIntegration" } }, "total": { "type": "integer" } } } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createAgentIntegration", "summary": "Add an integration to an agent (by connector_id and config, or link existing)", "tags": [ "Integrations" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "connector_id", "name" ], "properties": { "connector_id": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object" } } } } } }, "responses": { "201": { "description": "Integration created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentIntegration" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/integrations/{integrationId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "patch": { "operationId": "updateAgentIntegration", "summary": "Update an agent integration (e.g. name, config)", "tags": [ "Integrations" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "config": { "type": "object" } } } } } }, "responses": { "200": { "description": "Integration updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentIntegration" } } } }, "404": { "description": "Agent or integration not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAgentIntegration", "summary": "Remove an integration from an agent", "tags": [ "Integrations" ], "responses": { "200": { "description": "Integration removed" }, "404": { "description": "Agent or integration not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/integrations/{integrationId}/test": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "testAgentIntegration", "summary": "Test connectivity for an agent integration", "tags": [ "Integrations" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "404": { "description": "Agent or integration not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/llm-credentials/providers": { "get": { "operationId": "listLlmCredentialsProviders", "summary": "List LLM providers with configured status for current user", "tags": [ "LLM Credentials" ], "responses": { "200": { "description": "Providers with configured (true/false) per provider", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Display name for UI (e.g. OpenAI, Stels)" }, "configured": { "type": "boolean" }, "local": { "type": "boolean" }, "default_endpoint": { "type": "string" } } } } } } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/llm-credentials/{provider}": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "openai", "anthropic", "huggingface", "deepseek" ] } } ], "put": { "operationId": "setLlmProviderKey", "summary": "Set or update API key for an LLM provider", "tags": [ "LLM Credentials" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Provider API key (stored encrypted)" } } } } } }, "responses": { "200": { "description": "Key stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider_id": { "type": "string" }, "configured": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteLlmProviderKey", "summary": "Remove stored API key for an LLM provider", "tags": [ "LLM Credentials" ], "responses": { "200": { "description": "Key removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "provider_id": { "type": "string" } } } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/llm-credentials/{provider}/test": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "openai", "anthropic", "huggingface", "deepseek" ] } } ], "post": { "operationId": "testLlmProviderKey", "summary": "Test configured API key for an LLM provider", "tags": [ "LLM Credentials" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions": { "post": { "operationId": "createSession", "summary": "Create a session", "tags": [ "Sessions" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "metadata": { "type": "object" } } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Successful response" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listSessions", "summary": "List sessions", "tags": [ "Sessions" ], "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by agent ID" }, { "name": "team_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by team ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }, "total": { "type": "integer" } } } } }, "description": "Successful response" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getSession", "summary": "Get a session", "tags": [ "Sessions" ], "responses": { "200": { "description": "Session details" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "closeSession", "summary": "Close a session", "tags": [ "Sessions" ], "responses": { "200": { "description": "Session closed" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{sessionId}/messages": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listSessionMessages", "summary": "List session messages", "tags": [ "Sessions" ], "responses": { "200": { "description": "Messages" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "sendSessionMessage", "summary": "Send message", "tags": [ "Sessions" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Message sent" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{sessionId}/events": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "streamSessionEvents", "summary": "Stream session events (SSE)", "tags": [ "Sessions" ], "responses": { "200": { "description": "Event stream" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{sessionId}/share": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getSessionShare", "summary": "Get session share link status", "tags": [ "Sessions" ], "responses": { "200": { "description": "Share link details", "content": { "application/json": { "schema": { "type": "object", "properties": { "share_url": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "editor" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "404": { "description": "No share link for this session" } } }, "post": { "operationId": "createSessionShare", "summary": "Create session share link", "tags": [ "Sessions" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "viewer", "editor" ] }, "expires_in_hours": { "type": "number", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Share link created", "content": { "application/json": { "schema": { "type": "object", "properties": { "share_url": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "editor" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } }, "delete": { "operationId": "revokeSessionShare", "summary": "Revoke session share link", "tags": [ "Sessions" ], "responses": { "204": { "description": "Share revoked" } } } }, "/api/v1/sessions/{sessionId}/annotations": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listSessionAnnotations", "summary": "List session annotations", "tags": [ "Sessions" ], "responses": { "200": { "description": "Annotations list", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "message_id": { "type": "string" }, "content": { "type": "string" }, "author": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "resolved": { "type": "boolean" } } } } } } } } } } }, "post": { "operationId": "createSessionAnnotation", "summary": "Create annotation", "tags": [ "Sessions" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "message_id", "content" ], "properties": { "message_id": { "type": "string" }, "content": { "type": "string" } } } } } }, "responses": { "200": { "description": "Annotation created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "message_id": { "type": "string" }, "content": { "type": "string" }, "author": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "resolved": { "type": "boolean" } } } } } } } } }, "/api/v1/sessions/{sessionId}/annotations/{annotationId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "annotationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "patch": { "operationId": "updateSessionAnnotation", "summary": "Update annotation (e.g. resolve)", "tags": [ "Sessions" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "resolved": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Annotation updated" }, "404": { "description": "Annotation not found" } } }, "delete": { "operationId": "deleteSessionAnnotation", "summary": "Delete annotation", "tags": [ "Sessions" ], "responses": { "204": { "description": "Annotation deleted" }, "404": { "description": "Annotation not found" } } } }, "/api/v1/shared/{shareId}": { "parameters": [ { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "resolveSharedSession", "summary": "Resolve shared session (no auth)", "tags": [ "Sessions" ], "responses": { "200": { "description": "Shared session info", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "agent_name": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "editor" ] } } } } } }, "404": { "description": "Share not found or expired" } } } }, "/api/v1/runs": { "post": { "operationId": "createRun", "summary": "Create and schedule a run", "description": "Creates a run and schedules it for execution. Recommended: send Idempotency-Key header to avoid duplicate runs on retries; a repeated request with the same key returns the cached 202 response (same run_id).", "tags": [ "Runs" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "input": { "type": "object", "default": {} }, "resource_limits": { "type": "object" }, "metadata": { "type": "object" } } } } } }, "responses": { "202": { "description": "Run queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: session has queue_mode reject and already has an active run (queued, running, or paused)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getRun", "summary": "Get run status and result", "tags": [ "Runs" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "description": "Successful response" }, "404": { "description": "Run not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}/steps": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getRunSteps", "summary": "List steps for a run", "description": "Returns the ordered list of steps executed during a run, with per-step metrics including tokens, cost, and tool calls.", "tags": [ "Runs" ], "responses": { "200": { "description": "Run steps", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RunStep" } } } } } } }, "404": { "description": "Run not found" } } } }, "/api/v1/runs/{runId}/events": { "get": { "operationId": "streamRunEvents", "summary": "Stream run events via SSE", "description": "Real-time event stream for a run. Supports Last-Event-ID header for reconnection. Stream closes when run reaches terminal status. Each event payload includes stream_type: lifecycle (run.*), assistant (llm.chunk), tool (tool.*), or other — use it to filter client-side.", "tags": [ "Runs" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SSE event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "example": "no-cache" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } } } }, "400": { "description": "Missing runId", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}/cancel": { "post": { "operationId": "cancelRun", "summary": "Cancel a run", "tags": [ "Runs" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run cancelled" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}/pause": { "post": { "operationId": "pauseRun", "summary": "Pause a run", "tags": [ "Runs" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run paused" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}/resume": { "post": { "operationId": "resumeRun", "summary": "Resume a run", "tags": [ "Runs" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run resumed" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}/artifacts": { "get": { "operationId": "listRunArtifacts", "summary": "List run artifacts", "tags": [ "Runs" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artifact list" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/webhooks": { "post": { "operationId": "createWebhook", "summary": "Create a webhook subscription", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } }, "description": "Successful response" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listWebhooks", "summary": "List webhook subscriptions", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook list" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/webhooks/{webhookId}": { "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getWebhook", "summary": "Get a webhook subscription", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook details" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook subscription", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook deleted" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/webhooks/{webhookId}/test": { "post": { "operationId": "testWebhook", "summary": "Send test delivery", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test sent" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/webhooks/{webhookId}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List webhook deliveries", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deliveries" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/memory": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listMemories", "summary": "List recent memories for an agent", "tags": [ "Memory" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Memory list" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/memory/search": { "post": { "operationId": "searchMemory", "summary": "Search agent memories", "tags": [ "Memory" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "strategy": { "type": "string", "enum": [ "recency", "hybrid" ], "default": "hybrid" }, "limit": { "type": "integer", "default": 20 }, "types": { "type": "array", "items": { "type": "string", "enum": [ "episodic", "semantic", "procedural" ] } } } } } } }, "responses": { "200": { "description": "Search results" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/memory/ingest": { "post": { "operationId": "ingestMemory", "summary": "Ingest memory entry", "tags": [ "Memory" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Ingested" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/memory/{entryId}": { "get": { "operationId": "getMemoryEntry", "summary": "Get memory entry", "tags": [ "Memory" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entry" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteMemoryEntry", "summary": "Delete memory entry", "tags": [ "Memory" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Memory entry deleted (no content)" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/memory/core/{label}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getCoreMemoryBlock", "summary": "Get a core memory block", "tags": [ "Memory" ], "responses": { "200": { "description": "Core memory block", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoreMemoryBlock" } } } }, "404": { "description": "Block not found" } } }, "put": { "operationId": "updateCoreMemoryBlock", "summary": "Update a core memory block", "tags": [ "Memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Updated block", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoreMemoryBlock" } } } }, "404": { "description": "Block not found" } } } }, "/api/v1/agents/{agentId}/memory/entities/{entityId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getMemoriesByEntity", "summary": "Get memory entries associated with an entity", "tags": [ "Memory" ], "responses": { "200": { "description": "Entity memories", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryEntry" } } } } } } } } } }, "/api/v1/agents/{agentId}/experiments": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "createExperiment", "summary": "Create an evaluation experiment", "description": "Creates an experiment to compare evaluation results across multiple agent versions.", "tags": [ "Evaluations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "dataset_id", "variants" ], "properties": { "name": { "type": "string" }, "dataset_id": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "eval_run_id": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Experiment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } } } } }, "/api/v1/agents/{agentId}/experiments/{experimentId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getExperiment", "summary": "Get experiment details", "tags": [ "Evaluations" ], "responses": { "200": { "description": "Experiment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } }, "404": { "description": "Experiment not found" } } } }, "/api/v1/agents/{agentId}/schedule": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "operationId": "setSchedule", "summary": "Set/update agent schedule", "tags": [ "Scheduler" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cron" ], "properties": { "cron": { "type": "string", "example": "0 9 * * 1-5" }, "enabled": { "type": "boolean", "default": true }, "input": { "type": "object", "default": {} }, "timezone": { "type": "string", "default": "UTC" }, "on_failure": { "type": "string", "enum": [ "retry_next", "pause_schedule", "notify" ], "default": "retry_next" }, "max_concurrent_scheduled": { "type": "number", "default": 1 }, "autonomous_mode": { "type": "boolean", "description": "When true, schedule is fired by autonomous tick with reflection prompt instead of cron run with input." }, "reflection_prompt": { "type": "string", "description": "Prompt injected into run input when autonomous_mode is true (e.g. review pending work, plan next steps)." } } } } } }, "responses": { "200": { "description": "Schedule set" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getSchedule", "summary": "Get agent schedule", "tags": [ "Scheduler" ], "responses": { "200": { "description": "Schedule details, or null in response body when no schedule is set" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "removeSchedule", "summary": "Remove agent schedule", "tags": [ "Scheduler" ], "responses": { "200": { "description": "Schedule removed" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tenants/me": { "get": { "operationId": "getCurrentTenant", "summary": "Get current tenant", "tags": [ "Tenants" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "Successful response" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updateTenant", "summary": "Update current tenant settings", "tags": [ "Tenants" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "settings": { "type": "object" } } } } } }, "responses": { "200": { "description": "Tenant updated" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tenants/me/keys": { "post": { "operationId": "createApiKey", "summary": "Create a new API key", "tags": [ "Tenants" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "default": [ "agents:read", "agents:write", "runs:create", "runs:read", "notifications:read", "notifications:write", "memory:read", "memory:write", "files:read", "files:write" ] } } } } } }, "responses": { "201": { "description": "API key created (raw key shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listApiKeys", "summary": "List API keys", "tags": [ "Tenants" ], "responses": { "200": { "description": "API key list" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tenants/me/keys/{keyId}": { "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "tags": [ "Tenants" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key revoked" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/agent.json": { "get": { "operationId": "getAgentCard", "summary": "Get A2A agent card for discovery", "tags": [ "A2A" ], "parameters": [ { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A2A Agent Card JSON" }, "400": { "description": "Missing agent_id parameter", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/marketplace/search": { "get": { "operationId": "searchMarketplace", "summary": "Search marketplace listings", "tags": [ "Marketplace" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "coding", "writing", "research", "data", "automation", "creative", "education", "business", "other" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "rating", "popularity", "recency" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Marketplace listing results" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/marketplace/categories": { "get": { "operationId": "getMarketplaceCategories", "summary": "List marketplace categories", "tags": [ "Marketplace" ], "responses": { "200": { "description": "Category list" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/marketplace/listings": { "post": { "operationId": "publishListing", "summary": "Publish an agent to the marketplace", "tags": [ "Marketplace" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "name", "category" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "agent_version": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "readme": { "type": "string" }, "pricing": { "type": "object" }, "a2a_enabled": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Listing published" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/marketplace/listings/{listingId}": { "parameters": [ { "name": "listingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getListing", "summary": "Get marketplace listing details", "tags": [ "Marketplace" ], "responses": { "200": { "description": "Listing details" }, "404": { "description": "Listing not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "unpublishListing", "summary": "Unpublish a marketplace listing", "tags": [ "Marketplace" ], "responses": { "200": { "description": "Listing unpublished" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/marketplace/listings/{listingId}/rate": { "post": { "operationId": "rateListing", "summary": "Rate a marketplace listing", "tags": [ "Marketplace" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "listingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rating" ], "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "comment": { "type": "string" } } } } } }, "responses": { "201": { "description": "Rating submitted" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/import/hf": { "post": { "operationId": "importHfAgent", "summary": "Import an agent from HuggingFace agent.json format", "tags": [ "HF Interop" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "endpointUrl": { "type": "string" }, "servers": { "type": "array" } } } } } }, "responses": { "201": { "description": "Agent imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/export/hf": { "get": { "operationId": "exportHfAgent", "summary": "Export agent to HuggingFace agent.json format", "tags": [ "HF Interop" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "HF agent.json format" }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/usage": { "get": { "operationId": "getUsage", "summary": "Get current tenant usage", "tags": [ "Billing" ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "example": "2025-01" }, "description": "Billing period in YYYY-MM format. Defaults to current month." } ], "responses": { "200": { "description": "Aggregated usage data" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/usage/quota": { "get": { "operationId": "checkQuota", "summary": "Check tenant quota status", "tags": [ "Billing" ], "responses": { "200": { "description": "Quota check result with usage and limits" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/datasets": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "createDataset", "summary": "Create an evaluation dataset", "tags": [ "Evaluations" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "cases" ], "properties": { "name": { "type": "string" }, "cases": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "object" }, "expected_output": { "type": "object" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "responses": { "201": { "description": "Dataset created" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listDatasets", "summary": "List evaluation datasets for an agent", "tags": [ "Evaluations" ], "responses": { "200": { "description": "Dataset list" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/datasets/{datasetId}": { "get": { "operationId": "getDataset", "summary": "Get evaluation dataset details", "tags": [ "Evaluations" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dataset details" }, "404": { "description": "Dataset not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/evaluations": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "runEvaluation", "summary": "Run an evaluation suite against an agent", "tags": [ "Evaluations" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset_id" ], "properties": { "dataset_id": { "type": "string" }, "agent_version": { "type": "string" } } } } } }, "responses": { "201": { "description": "Evaluation run started" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listEvalRuns", "summary": "List evaluation runs for an agent", "tags": [ "Evaluations" ], "responses": { "200": { "description": "Evaluation run list" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/evaluations/{evalRunId}": { "get": { "operationId": "getEvalRun", "summary": "Get evaluation run results", "tags": [ "Evaluations" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "evalRunId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Evaluation run results" }, "404": { "description": "Eval run not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/admin/audit": { "get": { "operationId": "queryAuditLog", "summary": "Query admin audit log", "tags": [ "Admin" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Audit entries" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/admin/audit/{targetId}": { "get": { "operationId": "getAuditForTarget", "summary": "Get audit entries for a specific target", "tags": [ "Admin" ], "parameters": [ { "name": "targetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Target type (e.g., agent, run, tenant)" } ], "responses": { "200": { "description": "Audit entries for target" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/embeddings": { "post": { "operationId": "embeddings", "summary": "OpenAI-compatible embeddings", "description": "Generate embedding vectors for input text. Per Standats-Protocols §6.1. Uses platform-configured model (text-embedding-3-small).", "tags": [ "OpenAI-Compat" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "model": { "type": "string", "description": "Embedding model (optional; platform default used)" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Input text or array of texts" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "default": "float" }, "dimensions": { "type": "integer", "description": "Embedding dimensions (model-dependent)" } } } } } }, "responses": { "200": { "description": "Embeddings in OpenAI format" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Embedding API unavailable" } } } }, "/v1/chat/completions": { "post": { "operationId": "chatCompletion", "summary": "OpenAI-compatible chat completion", "description": "Maps OpenAI ChatCompletion requests to Snaga agent runs. The 'model' field maps to 'agent/' or a plain agent_id.", "tags": [ "OpenAI-Compat" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Agent ID or 'agent/'" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "type": [ "string", "null" ] } } } }, "temperature": { "type": "number" }, "max_tokens": { "type": "integer" }, "stream": { "type": "boolean", "default": false }, "tools": { "type": "array", "items": { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "JSON Schema Draft 2020-12 for tool parameters", "additionalProperties": true } } } } } }, "tool_choice": {} } } } } }, "responses": { "200": { "description": "Chat completion response (OpenAI format)" }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/files": { "post": { "operationId": "uploadFile", "summary": "Upload a file for multimodal content", "description": "Accepts multipart/form-data or base64 JSON. Files are stored with a 7-day TTL.", "tags": [ "Files" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } }, "application/json": { "schema": { "type": "object", "required": [ "data", "mime_type" ], "properties": { "data": { "type": "string", "format": "byte", "description": "Base64-encoded file content" }, "mime_type": { "type": "string" }, "filename": { "type": "string" } } } } } }, "responses": { "201": { "description": "File uploaded" }, "413": { "description": "File too large (max 20MB)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/files/{fileId}": { "get": { "operationId": "getFileMetadata", "summary": "Get file metadata", "tags": [ "Files" ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File metadata" }, "404": { "description": "File not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/a2a/tasks": { "post": { "operationId": "createA2ATask", "summary": "Create an A2A task", "description": "Creates a new agent-to-agent task and schedules the underlying run.", "tags": [ "A2A" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "messages" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "parts": { "type": "array", "items": { "type": "object" } } } } }, "metadata": { "type": "object" } } } } } }, "responses": { "202": { "description": "Task created and run scheduled" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/a2a/tasks/{taskId}": { "get": { "operationId": "getA2ATask", "summary": "Get A2A task status", "tags": [ "A2A" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task status" }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/a2a/tasks/{taskId}/cancel": { "post": { "operationId": "cancelA2ATask", "summary": "Cancel an A2A task", "tags": [ "A2A" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task cancelled" }, "409": { "description": "Task cannot be cancelled (already terminal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/versions": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "createAgentVersion", "summary": "Create a version snapshot of an agent", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "changelog": { "type": "string" } } } } } }, "responses": { "201": { "description": "Version created" }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getAgentVersionHistory", "summary": "Get version history for an agent", "tags": [ "Agents" ], "responses": { "200": { "description": "Version history" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/rollback": { "post": { "operationId": "rollbackAgent", "summary": "Rollback an agent to a previous version", "tags": [ "Agents" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "integer", "description": "Version number to rollback to" } } } } } }, "responses": { "200": { "description": "Agent rolled back" }, "404": { "description": "Agent or version not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/webhooks/stripe": { "post": { "operationId": "handleStripeWebhook", "summary": "Handle Stripe webhook events", "description": "Processes incoming Stripe events (invoice.paid, invoice.payment_failed, customer.subscription.deleted). Bypasses normal auth — uses Stripe signature verification.", "tags": [ "Billing" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string" }, "data": { "type": "object" } } } } } }, "responses": { "200": { "description": "Event processed" }, "400": { "description": "Invalid event format", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Stripe not configured" } } } }, "/api/v1/runs/{runId}/continue": { "post": { "operationId": "continueRun", "summary": "Continue a run from a continuation token", "description": "Decodes the token, loads the checkpoint, and re-schedules the run.", "tags": [ "Runs" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "continuation_token" ], "properties": { "continuation_token": { "type": "string", "description": "Opaque base64-encoded continuation token" } } } } } }, "responses": { "202": { "description": "Run re-queued from checkpoint" }, "404": { "description": "Checkpoint data not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}/queue-position": { "get": { "operationId": "getRunQueuePosition", "summary": "Get run queue position", "tags": [ "Runs" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Queue position", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "queue_position": { "type": "integer", "description": "0 means not in queue or currently running" } } } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}/wait": { "get": { "operationId": "waitRun", "summary": "Wait for run to reach terminal status", "description": "If the run is already completed, failed, cancelled, timeout, or guardrail_blocked, returns 200 with the run immediately. Otherwise polls until terminal status or timeout_sec. On timeout returns 202 with status still_running.", "tags": [ "Runs" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "timeout_sec", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 600, "default": 60 }, "description": "Max seconds to wait. Default from server config (e.g. 60)." } ], "responses": { "200": { "description": "Run reached terminal status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "202": { "description": "Timeout reached while run still in progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "still_running" }, "run_id": { "type": "string" }, "current_status": { "type": "string" } } } } } }, "404": { "description": "Run not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/admin/tenants/{tenantId}/suspend": { "put": { "operationId": "suspendTenant", "summary": "Suspend a tenant", "tags": [ "Admin" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Tenant suspended" }, "404": { "description": "Tenant not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/admin/tenants/{tenantId}/reactivate": { "put": { "operationId": "reactivateTenant", "summary": "Reactivate a suspended tenant", "tags": [ "Admin" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant reactivated" }, "404": { "description": "Tenant not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}/approve": { "post": { "operationId": "approveRun", "summary": "Approve a pending tool call (HITL)", "tags": [ "Runs" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run approved and resumed" }, "409": { "description": "Run not in awaiting_approval status", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{runId}/reject": { "post": { "operationId": "rejectRun", "summary": "Reject a pending tool call (HITL)", "tags": [ "Runs" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Run rejected" }, "409": { "description": "Run not in awaiting_approval status", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/openapi.json": { "get": { "operationId": "getOpenApiSpec", "summary": "Get OpenAPI spec", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 specification", "content": { "application/json": {} } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/register": { "post": { "operationId": "register", "tags": [ "Auth" ], "summary": "Register new user", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "User registered", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/request-code": { "post": { "operationId": "requestOtpCode", "tags": [ "Auth" ], "summary": "Request OTP code", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OTP code sent", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/verify-code": { "post": { "operationId": "verifyOtpCode", "tags": [ "Auth" ], "summary": "Verify OTP code", "description": "Expects body with email and code only (no request_id). Returns api_key to use as Bearer token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthVerifyCodeRequest" } } } }, "responses": { "200": { "description": "OTP verified, token returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthVerifyCodeResponse" } } } }, "400": { "description": "Bad Request: invalid/expired code, wrong body (use email + code), or validation (e.g. Valid email is required, Code is required)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/data-subject/access": { "get": { "operationId": "dataSubjectAccess", "tags": [ "GDPR" ], "summary": "Data subject access request", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Personal data export", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/data-subject/erasure": { "post": { "operationId": "dataSubjectErasure", "tags": [ "GDPR" ], "summary": "Data subject erasure request", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Erasure completed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/teams": { "get": { "operationId": "listTeams", "tags": [ "Teams" ], "summary": "List teams", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Teams list", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createTeam", "tags": [ "Teams" ], "summary": "Create a team", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Team created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/teams/{teamId}": { "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getTeam", "tags": [ "Teams" ], "summary": "Get team", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Team details", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Team not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/teams/{teamId}/chat": { "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "sendTeamChatMessage", "tags": [ "Teams" ], "summary": "Send team chat message", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Message sent", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/companies": { "get": { "operationId": "listCompanies", "tags": [ "Companies" ], "summary": "List companies", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Companies list", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createCompany", "tags": [ "Companies" ], "summary": "Create a company", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Company created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/companies/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getCompany", "tags": [ "Companies" ], "summary": "Get company", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Company details", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Company not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updateCompany", "tags": [ "Companies" ], "summary": "Update company", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated company", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "operationId": "deleteCompany", "tags": [ "Companies" ], "summary": "Delete company", "responses": { "204": { "description": "Company deleted" } } } }, "/api/v1/knowledge-bases": { "get": { "operationId": "listKnowledgeBases", "tags": [ "Knowledge" ], "summary": "List knowledge bases", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Knowledge bases list", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createKnowledgeBase", "tags": [ "Knowledge" ], "summary": "Create a knowledge base", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Knowledge base created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/knowledge-bases/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getKnowledgeBase", "tags": [ "Knowledge" ], "summary": "Get knowledge base", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Knowledge base details", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Knowledge base not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/templates": { "get": { "operationId": "listTemplates", "tags": [ "Templates" ], "summary": "List templates", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Templates list", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/templates/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getTemplate", "tags": [ "Templates" ], "summary": "Get template", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Template details", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Template not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/notifications": { "get": { "operationId": "listNotifications", "tags": [ "Notifications" ], "summary": "List notifications", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "unread", "in": "query", "schema": { "type": "boolean" }, "description": "Filter to unread only" } ], "responses": { "200": { "description": "Notifications list", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/notifications/{id}/read": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "operationId": "markNotificationRead", "tags": [ "Notifications" ], "summary": "Mark notification as read", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Notification marked as read", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Notification not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/guardrails": { "get": { "operationId": "listGuardrails", "tags": [ "Guardrails" ], "summary": "List guardrails", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Guardrails list", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/notifications/unread": { "get": { "operationId": "getUnreadCount", "tags": [ "Notifications" ], "summary": "Get unread notification count", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Unread count", "content": { "application/json": { "schema": { "type": "object", "properties": { "unread_count": { "type": "integer" } } } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/notifications/read-all": { "put": { "operationId": "markAllNotificationsRead", "tags": [ "Notifications" ], "summary": "Mark all notifications as read", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "All marked as read", "content": { "application/json": { "schema": { "type": "object", "properties": { "marked": { "type": "integer" } } } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces": { "get": { "operationId": "listWorkspaces", "tags": [ "Workspaces" ], "summary": "List all workspaces", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workspace list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createWorkspace", "tags": [ "Workspaces" ], "summary": "Create a workspace", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Workspace created", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getWorkspace", "tags": [ "Workspaces" ], "summary": "Get workspace metadata", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workspace metadata" }, "404": { "description": "Workspace not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateWorkspace", "tags": [ "Workspaces" ], "summary": "Update workspace name", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Workspace updated" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteWorkspace", "tags": [ "Workspaces" ], "summary": "Delete workspace and all files", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workspace deleted" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/assign": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "assignWorkspace", "tags": [ "Workspaces" ], "summary": "Assign agent/team/company to workspace", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "team_id": { "type": "string" }, "company_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Assignment created" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "unassignWorkspace", "tags": [ "Workspaces" ], "summary": "Unassign agent/team/company from workspace", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Assignment removed" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/files": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listWorkspaceFiles", "tags": [ "Workspaces" ], "summary": "List files in workspace directory", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "path", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Directory path to list" } ], "responses": { "200": { "description": "File listing" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "uploadWorkspaceFile", "tags": [ "Workspaces" ], "summary": "Upload or update a file", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "File path within workspace" } ], "responses": { "200": { "description": "File uploaded" }, "403": { "$ref": "#/components/responses/Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteWorkspaceFile", "tags": [ "Workspaces" ], "summary": "Delete a file", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File deleted" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/files/content": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "downloadWorkspaceFile", "tags": [ "Workspaces" ], "summary": "Download file content", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File content (binary)" }, "404": { "description": "File not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/files/move": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "moveWorkspaceFile", "tags": [ "Workspaces" ], "summary": "Move/rename a file", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_path", "to_path" ], "properties": { "from_path": { "type": "string" }, "to_path": { "type": "string" } } } } } }, "responses": { "200": { "description": "File moved" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/share": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "shareWorkspace", "tags": [ "Workspaces" ], "summary": "Share workspace with an agent", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Workspace shared" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/share/{agentId}": { "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "operationId": "revokeWorkspaceShare", "tags": [ "Workspaces" ], "summary": "Revoke workspace sharing", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Share revoked" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/workspace/files": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listAgentWorkspaceFiles", "tags": [ "Workspaces" ], "summary": "List agent workspace files (shortcut)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "path", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File listing" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programs": { "get": { "operationId": "listPrograms", "tags": [ "Programs" ], "summary": "List programs", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Programs list", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createProgram", "tags": [ "Programs" ], "summary": "Create a program (curriculum)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "agent_id" ], "properties": { "name": { "type": "string" }, "agent_id": { "type": "string" }, "description": { "type": "string" }, "listing_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Program created" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programs/{programId}": { "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getProgram", "tags": [ "Programs" ], "summary": "Get program", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Program details" }, "404": { "description": "Program not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programs/{programId}/apply": { "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "applyProgram", "tags": [ "Programs" ], "summary": "Apply program to session (create todos)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" }, "start_date": { "type": "string" }, "agent_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Program applied" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/providers": { "get": { "operationId": "listProviders", "tags": [ "Providers" ], "summary": "List configured LLM providers", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Provider list with models and status", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/providers/{providerId}/models": { "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listProviderModels", "tags": [ "Providers" ], "summary": "Fetch real models from provider API", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Model list from provider; use endpoint_url when creating/updating agents so clients need not hardcode provider endpoints.", "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "endpoint_url", "models" ], "properties": { "provider": { "type": "string", "description": "Provider id (e.g. openai, huggingface)." }, "endpoint_url": { "type": "string", "description": "Base URL for this provider's API (e.g. https://api.openai.com/v1). Empty for custom." }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created": { "type": "integer" }, "capabilities": { "type": "object" } } } }, "error": { "type": "string", "description": "Present when models could not be fetched (e.g. provider not configured)." } } } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/providers/image-providers": { "get": { "operationId": "listImageProviders", "tags": [ "Providers" ], "summary": "List image generation providers and models", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Image provider list", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/playground/agents/{agentId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getPlaygroundCanvas", "tags": [ "Playground" ], "summary": "Load agent canvas state for visual builder", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Canvas state" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "savePlaygroundCanvas", "tags": [ "Playground" ], "summary": "Save agent canvas state", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Canvas saved" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/playground/agents/{agentId}/run": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "runPlayground", "tags": [ "Playground" ], "summary": "Execute agent in playground", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Playground run result" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/playground/templates": { "get": { "operationId": "listPlaygroundTemplates", "tags": [ "Playground" ], "summary": "List starter templates for visual builder", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Template list" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/mcp": { "get": { "operationId": "mcpSse", "tags": [ "MCP" ], "summary": "MCP SSE transport (Server-Sent Events)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SSE event stream for MCP", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "mcpJsonRpc", "tags": [ "MCP" ], "summary": "MCP JSON-RPC endpoint", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "method": { "type": "string" }, "params": { "type": "object" }, "id": {} } } } } }, "responses": { "200": { "description": "JSON-RPC response" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acp/session": { "post": { "operationId": "createAcpSession", "tags": [ "ACP" ], "summary": "Create ACP bridge session", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "ACP session created" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acp/session/{sessionId}/message": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "sendAcpMessage", "tags": [ "ACP" ], "summary": "Send message to ACP session", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Message processed" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acp/session/{sessionId}/events": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "streamAcpEvents", "tags": [ "ACP" ], "summary": "Stream ACP session events (SSE)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SSE event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/a2a/tasks/{taskId}/events": { "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "streamA2ATaskEvents", "tags": [ "A2A" ], "summary": "Stream A2A task status updates (SSE)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SSE event stream for task updates", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "example": "no-cache" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/a2a": { "post": { "operationId": "a2aJsonRpc", "tags": [ "A2A" ], "summary": "A2A JSON-RPC 2.0 endpoint", "description": "Handles tasks/send, tasks/sendSubscribe, tasks/get, tasks/cancel, tasks/pushNotification/set, tasks/pushNotification/get via JSON-RPC 2.0.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "method": { "type": "string", "enum": [ "tasks/send", "tasks/sendSubscribe", "tasks/get", "tasks/cancel", "tasks/pushNotification/set", "tasks/pushNotification/get" ] }, "params": { "type": "object" }, "id": {} } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/models": { "get": { "operationId": "listModels", "tags": [ "OpenAI-Compat" ], "summary": "List available models (OpenAI-compatible)", "description": "Returns agents as models in OpenAI model list format.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Model list in OpenAI format" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/responses": { "post": { "operationId": "createResponse", "tags": [ "OpenAI-Compat" ], "summary": "Create response (OpenAI Responses API)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Response object" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/responses/{responseId}": { "parameters": [ { "name": "responseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getResponse", "tags": [ "OpenAI-Compat" ], "summary": "Get response by ID (OpenAI Responses API)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Response object" }, "404": { "description": "Response not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/admin/config/pricing": { "get": { "operationId": "getAdminPricing", "tags": [ "Admin" ], "summary": "Get pricing configuration", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Pricing config" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updateAdminPricing", "tags": [ "Admin" ], "summary": "Update pricing configuration", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Pricing updated" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/public/landing-stats": { "get": { "operationId": "getPublicLandingStats", "tags": [ "Meta" ], "summary": "Get public landing page statistics", "security": [], "responses": { "200": { "description": "Public stats", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/search": { "get": { "operationId": "search", "tags": [ "Meta" ], "summary": "Search across agents, sessions, runs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "agent", "session", "run" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Search results" }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agentId}/versions/{versionId}/diff": { "get": { "operationId": "getAgentVersionDiff", "tags": [ "Agents" ], "summary": "Diff between two agent versions", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "compare_to", "in": "query", "schema": { "type": "string" }, "description": "Version to compare against (defaults to versionId-1)" } ], "responses": { "200": { "description": "Version diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "version_from": { "type": "integer" }, "version_to": { "type": "integer" }, "diff": { "type": "object", "additionalProperties": { "type": "object", "properties": { "from": {}, "to": {} } } }, "changed_fields": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/v1/agents/{agentId}/traffic": { "get": { "operationId": "getAgentTraffic", "tags": [ "Agents" ], "summary": "Get traffic split configuration", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Traffic split", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "weight": { "type": "number" } } } }, "updated_at": { "type": [ "string", "null" ] } } } } } } } }, "put": { "operationId": "setAgentTraffic", "tags": [ "Agents" ], "summary": "Set traffic split configuration", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "weight": { "type": "number" } }, "required": [ "version", "weight" ] } } }, "required": [ "entries" ] } } } }, "responses": { "200": { "description": "Updated traffic split", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/agents/{agentId}/system-card": { "get": { "operationId": "getAgentSystemCard", "tags": [ "Agents" ], "summary": "Get EU AI Act Annex IV system card", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "markdown" ] }, "description": "Output format (default: json)" } ], "responses": { "200": { "description": "System card", "content": { "application/json": { "schema": { "type": "object" } }, "text/markdown": { "schema": { "type": "string" } } } } } } }, "/api/v1/agents/{agentId}/fria": { "get": { "operationId": "getAgentFria", "tags": [ "Agents" ], "summary": "Get Fundamental Rights Impact Assessment", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "FRIA report", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "operationId": "createAgentFria", "tags": [ "Agents" ], "summary": "Create or update FRIA report", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated FRIA report", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/agents/{agentId}/risk-classification": { "patch": { "operationId": "updateAgentRiskClassification", "tags": [ "Agents" ], "summary": "Update EU AI Act risk classification (admin only)", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated classification", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/agents/{agentId}/scorers": { "get": { "operationId": "listAgentScorers", "tags": [ "Evaluations" ], "summary": "List custom evaluation scorers", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scorers list", "content": { "application/json": { "schema": { "type": "object", "properties": { "scorers": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "operationId": "createAgentScorer", "tags": [ "Evaluations" ], "summary": "Create custom webhook scorer", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Scorer created", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/agents/import/hf-hub": { "post": { "operationId": "importAgentFromHfHub", "tags": [ "HF Interop" ], "summary": "Import agent from HuggingFace Hub", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repo_id": { "type": "string", "description": "HuggingFace repo ID (e.g. user/repo)" }, "token": { "type": "string", "description": "Optional HF API token for private repos" } }, "required": [ "repo_id" ] } } } }, "responses": { "201": { "description": "Agent imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/api/v1/agents/{agentId}/export/hf-hub": { "get": { "operationId": "exportAgentToHfHub", "tags": [ "HF Interop" ], "summary": "Export agent in HuggingFace format", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "HF-compatible agent.json", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/runs/{runId}/replay": { "post": { "operationId": "replayRun", "tags": [ "Runs" ], "summary": "Replay a run for determinism check", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Replay started", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/runs/{runId}/checkpoint": { "post": { "operationId": "createRunCheckpoint", "tags": [ "Runs" ], "summary": "Create checkpoint for a run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Checkpoint created", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/runs/{runId}/checkpoints": { "get": { "operationId": "listRunCheckpoints", "tags": [ "Runs" ], "summary": "List checkpoints for a run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Checkpoints list", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkpoints": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/v1/runs/{runId}/events/export": { "get": { "operationId": "exportRunEvents", "tags": [ "Runs" ], "summary": "Export run events as JSONL", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "JSONL event stream", "content": { "application/x-ndjson": { "schema": { "type": "string" } } } } } } }, "/api/v1/runs/{runId}/audit-log": { "get": { "operationId": "getRunAuditLog", "tags": [ "Runs" ], "summary": "Get audit trail for a run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audit log entries", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/runs/{runId}/feedback": { "get": { "operationId": "getRunFeedback", "tags": [ "Runs" ], "summary": "Get user feedback for a run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "message_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Feedback data", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "operationId": "setRunFeedback", "tags": [ "Runs" ], "summary": "Save user feedback/reaction for a run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated feedback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sessions/{sessionId}/audit-log": { "get": { "operationId": "getSessionAuditLog", "tags": [ "Sessions" ], "summary": "Get audit log scoped to session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audit log entries", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sessions/{sessionId}/branch": { "post": { "operationId": "createSessionBranch", "tags": [ "Sessions" ], "summary": "Create a branch point in session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Branch created", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sessions/{sessionId}/branches": { "get": { "operationId": "listSessionBranches", "tags": [ "Sessions" ], "summary": "List session branches", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branches list", "content": { "application/json": { "schema": { "type": "object", "properties": { "branches": { "type": "array", "items": { "type": "object", "properties": { "branch_id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string" } } } }, "active_branch": { "type": "string" } } } } } } } } }, "/api/v1/sessions/{sessionId}/branches/{branchId}/activate": { "put": { "operationId": "activateSessionBranch", "tags": [ "Sessions" ], "summary": "Switch active branch", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Branch activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } } } } }, "/api/v1/sessions/{sessionId}/todos": { "get": { "operationId": "listSessionTodos", "tags": [ "Sessions" ], "summary": "List session todos", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Todos list", "content": { "application/json": { "schema": { "type": "object", "properties": { "todos": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "operationId": "createSessionTodo", "tags": [ "Sessions" ], "summary": "Create a todo in session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "due_at": { "type": "string", "format": "date-time" }, "assign_agent_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "title" ] } } } }, "responses": { "201": { "description": "Todo created", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sessions/{sessionId}/todos/{todoId}": { "patch": { "operationId": "updateSessionTodo", "tags": [ "Sessions" ], "summary": "Update a todo", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "todoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated todo", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "operationId": "deleteSessionTodo", "tags": [ "Sessions" ], "summary": "Delete a todo", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "todoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Todo deleted" } } } }, "/api/v1/sessions/{sessionId}/todos/{todoId}/confirm": { "post": { "operationId": "confirmSessionTodo", "tags": [ "Sessions" ], "summary": "Confirm or cancel a todo execution", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "todoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Todo confirmed", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sessions/{sessionId}/artifacts": { "get": { "operationId": "listSessionArtifacts", "tags": [ "Sessions" ], "summary": "List artifacts across all runs in session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Artifacts list", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" } } } } } } } } } }, "/api/v1/sessions/{sessionId}/runs/{runId}/feedback": { "get": { "operationId": "getSessionRunFeedback", "tags": [ "Sessions" ], "summary": "Get feedback for a run in session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "message_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Feedback data", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "operationId": "setSessionRunFeedback", "tags": [ "Sessions" ], "summary": "Save feedback/reaction for a session run", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated feedback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/billing/plans": { "get": { "operationId": "listBillingPlans", "tags": [ "Billing" ], "summary": "List available billing plans", "responses": { "200": { "description": "Plans list", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "limits": { "type": "object" }, "current": { "type": "boolean" }, "checkout_available": { "type": "boolean" }, "price_amount_cents": { "type": "integer" }, "price_currency": { "type": "string" } } } } } } } } } } } }, "/api/v1/billing/checkout-session": { "post": { "operationId": "createCheckoutSession", "tags": [ "Billing" ], "summary": "Create Stripe checkout session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string" }, "success_url": { "type": "string" }, "cancel_url": { "type": "string" } }, "required": [ "plan_id" ] } } } }, "responses": { "200": { "description": "Checkout URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } } } } } } }, "/api/v1/usage/timeseries": { "get": { "operationId": "getUsageTimeseries", "tags": [ "Billing" ], "summary": "Get usage analytics over time", "parameters": [ { "name": "metric", "in": "query", "schema": { "type": "string", "enum": [ "runs", "tokens", "cost" ], "default": "runs" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 14, "maximum": 90 } }, { "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Timeseries data", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "number" } } } } } } } } } } } }, "/api/v1/admin/tenants": { "get": { "operationId": "listTenants", "tags": [ "Admin" ], "summary": "List all tenants (super admin only)", "responses": { "200": { "description": "Tenants list", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenants": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } }, "total": { "type": "integer" } } } } } } } }, "post": { "operationId": "createTenant", "tags": [ "Admin" ], "summary": "Create new tenant", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Tenant created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } } } } }, "/api/v1/admin/tenants/{tenantId}": { "get": { "operationId": "getTenant", "tags": [ "Admin" ], "summary": "Get tenant details", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } } } }, "patch": { "operationId": "updateTenant", "tags": [ "Admin" ], "summary": "Update tenant", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } } } } }, "/api/v1/admin/tenants/{tenantId}/usage": { "get": { "operationId": "getTenantUsage", "tags": [ "Admin" ], "summary": "Get tenant usage metrics", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "query", "schema": { "type": "string" }, "description": "ISO YYYY-MM period (defaults to current month)" } ], "responses": { "200": { "description": "Usage data", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "period": { "type": "string" }, "usage": { "type": "object" } } } } } } } } }, "/api/v1/marketplace/listings/{listingId}/reviews": { "get": { "operationId": "getListingReviews", "tags": [ "Marketplace" ], "summary": "Get reviews for a listing", "security": [], "parameters": [ { "name": "listingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reviews list", "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "cursor": { "type": "string" } } } } } } } } }, "/api/v1/marketplace/listings/{listingId}/subscribe": { "post": { "operationId": "subscribeToListing", "tags": [ "Marketplace" ], "summary": "Subscribe to a marketplace listing", "parameters": [ { "name": "listingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "stripe_subscription_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Subscribed", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "operationId": "unsubscribeFromListing", "tags": [ "Marketplace" ], "summary": "Unsubscribe from a listing", "parameters": [ { "name": "listingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Unsubscribed", "content": { "application/json": { "schema": { "type": "object", "properties": { "unsubscribed": { "type": "boolean" }, "listing_id": { "type": "string" } } } } } } } } }, "/api/v1/marketplace/subscriptions": { "get": { "operationId": "listSubscriptions", "tags": [ "Marketplace" ], "summary": "List user subscriptions", "responses": { "200": { "description": "Subscriptions list", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/v1/marketplace/listings/{listingId}/invoke": { "post": { "operationId": "invokeListingAgent", "tags": [ "Marketplace" ], "summary": "Invoke a marketplace agent", "parameters": [ { "name": "listingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object" } }, "required": [ "input" ] } } } }, "responses": { "202": { "description": "Invocation started", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/companies/{companyId}/pause": { "post": { "operationId": "pauseCompany", "tags": [ "Companies" ], "summary": "Pause company operations", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } } } } }, "/api/v1/companies/{companyId}/resume": { "post": { "operationId": "resumeCompany", "tags": [ "Companies" ], "summary": "Resume company operations", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company resumed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } } } } }, "/api/v1/companies/{companyId}/objectives": { "get": { "operationId": "getCompanyObjectives", "tags": [ "Companies" ], "summary": "Get company strategic objectives", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Objectives", "content": { "application/json": { "schema": { "type": "object", "properties": { "trees": { "type": "array", "items": { "type": "object" } }, "objectives": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/v1/companies/{companyId}/activity": { "get": { "operationId": "getCompanyActivity", "tags": [ "Companies" ], "summary": "Get company activity log", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Activity log", "content": { "application/json": { "schema": { "type": "object", "properties": { "activity": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/v1/companies/{companyId}/budget": { "get": { "operationId": "getCompanyBudget", "tags": [ "Companies" ], "summary": "Get company budget allocation", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Budget info", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_usd": { "type": "number" }, "spent_usd": { "type": "number" }, "daily_limit_usd": { "type": "number" }, "alert_threshold_pct": { "type": "number" }, "remaining_usd": { "type": "number" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/run-command": { "post": { "operationId": "runWorkspaceCommand", "tags": [ "Workspaces" ], "summary": "Execute shell command in workspace", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string" }, "workdir": { "type": "string" }, "timeout_sec": { "type": "integer" } }, "required": [ "command" ] } } } }, "responses": { "200": { "description": "Command output", "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "type": "string" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/search": { "get": { "operationId": "searchWorkspaceFiles", "tags": [ "Workspaces" ], "summary": "Search files in workspace", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" }, { "name": "glob", "in": "query", "schema": { "type": "string" }, "description": "File glob pattern" }, { "name": "regex", "in": "query", "schema": { "type": "string", "enum": [ "true", "1" ] }, "description": "Treat query as regex" } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "lineNumber": { "type": "integer" }, "line": { "type": "string" }, "match": { "type": "string" } } } }, "total": { "type": "integer" } } } } } } } } }, "/api/v1/templates/{templateId}/deploy": { "post": { "operationId": "deployTemplate", "tags": [ "Templates" ], "summary": "Deploy template as agent", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Agent deployed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/api/v1/teams/{teamId}/runs": { "get": { "operationId": "listTeamRuns", "tags": [ "Teams" ], "summary": "List runs for a team", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Team runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "string" }, "runs": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } } } } }, "post": { "operationId": "startTeamRun", "tags": [ "Teams" ], "summary": "Start a team run", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object" }, "addressed_to": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "chat_mode": { "type": "string", "enum": [ "plan", "chat" ] } } } } } }, "responses": { "202": { "description": "Team run started", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/teams/{teamId}/runs/{runId}/events": { "get": { "operationId": "streamTeamRunEvents", "tags": [ "Teams" ], "summary": "Stream team run events (SSE)", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } } } } }, "/api/v1/knowledge-bases/{kbId}/documents": { "get": { "operationId": "listKbDocuments", "tags": [ "Knowledge" ], "summary": "List documents in knowledge base", "parameters": [ { "name": "kbId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Documents list", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } } } } }, "post": { "operationId": "ingestKbDocument", "tags": [ "Knowledge" ], "summary": "Ingest document into knowledge base", "parameters": [ { "name": "kbId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": { "type": "string" }, "content": { "type": "string" }, "filename": { "type": "string" } } } } } }, "responses": { "201": { "description": "Document ingested", "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string" }, "name": { "type": "string" }, "chunks_created": { "type": "integer" }, "status": { "type": "string" } } } } } } } } }, "/api/v1/guardrails/{guardrailId}": { "delete": { "operationId": "deleteGuardrail", "tags": [ "Guardrails" ], "summary": "Delete a guardrail", "parameters": [ { "name": "guardrailId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Guardrail deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "guardrail_id": { "type": "string" } } } } } } } } } }, "tags": [ { "name": "Health", "description": "Health checks, readiness, and metrics" }, { "name": "Bootstrap", "description": "First-time platform setup" }, { "name": "Agents", "description": "Agent CRUD and versioning" }, { "name": "Sessions", "description": "Conversation sessions" }, { "name": "Runs", "description": "Agent execution runs, SSE streaming, HITL, continuation" }, { "name": "Webhooks", "description": "Webhook subscriptions" }, { "name": "Memory", "description": "Agent memory management" }, { "name": "Scheduler", "description": "Cron-based scheduling" }, { "name": "Tenants", "description": "Tenant management and API keys" }, { "name": "A2A", "description": "Agent-to-Agent protocol: discovery and task execution" }, { "name": "Marketplace", "description": "Agent marketplace: publish, search, rate" }, { "name": "HF Interop", "description": "HuggingFace Hub import/export" }, { "name": "Billing", "description": "Usage tracking, quota management, and Stripe webhooks" }, { "name": "Evaluations", "description": "Agent evaluation datasets and runs" }, { "name": "Files", "description": "File upload for multimodal content" }, { "name": "OpenAI-Compat", "description": "OpenAI-compatible ChatCompletion endpoint" }, { "name": "Admin", "description": "Admin audit log and tenant management" }, { "name": "Meta", "description": "API metadata" }, { "name": "Auth", "description": "User registration and OTP authentication" }, { "name": "GDPR", "description": "Data subject access and erasure requests" }, { "name": "Teams", "description": "Team management and team chat" }, { "name": "Companies", "description": "Company management" }, { "name": "Knowledge", "description": "Knowledge base management" }, { "name": "Templates", "description": "Agent templates" }, { "name": "Notifications", "description": "User notifications" }, { "name": "Guardrails", "description": "Guardrail policies" }, { "name": "Workspaces", "description": "Workspace management, file storage, and sharing" }, { "name": "Programs", "description": "Program (curriculum) management" }, { "name": "Providers", "description": "LLM provider discovery and model listing" }, { "name": "Playground", "description": "Visual builder and agent playground" }, { "name": "MCP", "description": "Model Context Protocol server endpoints" }, { "name": "ACP", "description": "Agent Communication Protocol bridge sessions" }, { "name": "Integrations", "description": "OAuth integrations and connector management" }, { "name": "LLM Credentials", "description": "LLM provider API key management" } ] }