{ "openapi": "3.1.0", "info": { "title": "UARP — Universal Agent Runtime Platform", "version": "0.2.0", "description": "API for managing AI agents, runs, sessions, and supporting infrastructure.\n\nAuth: bearer API key (`Authorization: Bearer uarp__`). Browser SSE/WebSocket clients that cannot set headers may pass the same key as `?token=` query param or `uarp_auth_token` cookie.\n\nIdempotency: every mutating `/api/v1/*` request accepts an `Idempotency-Key` header; replays within 24 h return the cached response with `X-Idempotency-Replayed: true`.", "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": "uarp__", "description": "API key in `Authorization: Bearer uarp__` header.\n\nScope catalogue (from `requireScope(auth, ...)` calls in route handlers): `admin`, `agents:read`, `agents:write`, `api_keys:read`, `api_keys:write`, `billing:read`, `evaluations:read`, `evaluations:write`, `events:read`, `files:read`, `files:write`, `guardrails:read`, `guardrails:write`, `marketplace:invoke`, `marketplace:read`, `marketplace:write`, `memory:read`, `memory:write`, `notifications:read`, `notifications:write`, `read:analytics`, `runs:create`, `runs:read`, `search:read`, `sessions:read`, `sessions:write`, `tenants:write`, `users:read`, `users:write`, `webhooks:read`, `webhooks:write`.\n\nAn empty `[]` under `bearerAuth` in an operation `security` block means any authenticated key passes; explicit scope strings restrict to keys carrying that scope. Most `/admin/*` endpoints additionally require role `admin` (RBAC layer beyond scope)." }, "queryTokenAuth": { "type": "apiKey", "in": "query", "name": "token", "description": "Same API key passed via `?token=_>` query param. Used for SSE/WebSocket/file content endpoints that cannot set request headers from a browser. For `/runs/{runId}/events` and `/sessions/{sessionId}/events` the recommended flow is to mint a short-lived token via `POST /api/v1/auth/sse-tokens` (60 s TTL, scope-restricted)." }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "uarp_auth_token", "description": "Same API key set as a cookie. Used by the builder web app and any HTML rendering endpoint behind same-origin auth." }, "webSocketProtocolAuth": { "type": "apiKey", "in": "header", "name": "Sec-WebSocket-Protocol", "description": "WebSocket upgrade only: subprotocol of the form `uarp.`. Used by `/api/v1/bridge/ws` and other WebSocket upgrade routes." } }, "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", "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" }, "model_override": { "type": "object", "nullable": true, "description": "Per-conversation model override (in-chat model switcher). When set, runs in this session resolve their LLM from this config instead of the agent's default. Absent → agent default.", "properties": { "provider": { "type": "string" }, "model_ref": { "type": "string" }, "endpoint_url": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": true } }, "required": [ "provider", "model_ref" ] } }, "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" }, "tool_calls": { "type": "array", "description": "Persisted on assistant entries when the run executed tools. Reload re-paints these blocks underneath the assistant turn (matches what the SSE stream renders during the live run).", "items": { "type": "object", "required": [ "id", "name", "status" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "done", "error" ] }, "input": { "type": "string" }, "output": { "type": "string" }, "duration_ms": { "type": "integer" }, "error": { "type": "string" } } } }, "thinking": { "type": "string", "description": "Reasoning / thinking content (DeepSeek `reasoning_content`, Anthropic extended thinking, GLM/Qwen `` blocks). Persisted on assistant entries so reload re-paints the Thinking section above the assistant text." } } }, "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" ] }, "AgentAnalyticsSummary": { "type": "object", "description": "Output of summariseAgents (analytics.ts) — same shape for /admin/analytics/agents and /analytics/agents (tenant-scoped).", "properties": { "range": { "type": "object", "properties": { "days": { "type": "integer" } }, "required": [ "days" ] }, "total": { "type": "integer" }, "by_execution_mode": { "type": "object", "properties": { "cloud": { "type": "integer" }, "bridge": { "type": "integer" } } }, "bridge": { "type": "object", "properties": { "online": { "type": "integer" }, "stale": { "type": "integer" }, "offline": { "type": "integer" }, "machines_total": { "type": "integer" } } }, "runs_total": { "type": "integer" }, "cost_total_usd": { "type": "number" }, "tokens_total": { "type": "integer" }, "top_by_runs": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } }, "top_by_cost": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } } }, "required": [ "range", "total", "agents" ] }, "AgentSummary": { "type": "object", "properties": { "agent_id": { "type": "string" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "execution_mode": { "type": "string", "enum": [ "cloud", "bridge" ] }, "status": { "type": "string" }, "bridge_status": { "type": "string", "enum": [ "online", "stale", "offline" ] }, "machine_count": { "type": "integer" }, "runs": { "type": "integer" }, "cost_usd": { "type": "number" }, "tokens": { "type": "integer" } }, "required": [ "agent_id", "tenant_id", "name", "execution_mode", "status" ] }, "ConstitutionRule": { "type": "object", "properties": { "rule_id": { "type": "string" }, "principle": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warning", "error", "blocker" ] }, "scope": { "type": "string", "enum": [ "global", "tenant", "agent" ] } }, "required": [ "rule_id", "principle" ] }, "Constitution": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/ConstitutionRule" } }, "version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "rules", "version" ] }, "EnforcementResult": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule_id": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warning", "error", "blocker" ] }, "message": { "type": "string" } }, "required": [ "rule_id", "severity", "message" ] } } }, "required": [ "allowed", "violations" ] }, "GovernanceLedgerEntry": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "actor_agent_id": { "type": [ "string", "null" ] }, "subject_agent_id": { "type": [ "string", "null" ] }, "rule_id": { "type": [ "string", "null" ] }, "details": { "type": "object", "additionalProperties": true }, "ts": { "type": "string", "format": "date-time" }, "prev_hash": { "type": [ "string", "null" ] }, "hash": { "type": "string" } }, "required": [ "id", "kind", "ts", "hash" ] }, "Goal": { "type": "object", "properties": { "id": { "type": "string" }, "agent_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "achieved", "abandoned", "expired" ] }, "target_date": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agent_id", "status" ] }, "VotingProposal": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "proposer_agent_id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "open", "closed", "vetoed", "executed" ] }, "opens_at": { "type": "string", "format": "date-time" }, "closes_at": { "type": "string", "format": "date-time" }, "result": { "type": [ "object", "null" ] } }, "required": [ "id", "status" ] }, "Ballot": { "type": "object", "properties": { "id": { "type": "string" }, "proposal_id": { "type": "string" }, "agent_id": { "type": "string" }, "vote": { "type": "string", "enum": [ "yes", "no", "abstain" ] }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "reasoning": { "type": "string" }, "signature": { "type": "string" }, "cast_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "proposal_id", "agent_id", "vote", "cast_at" ] }, "ArbiterCase": { "type": "object", "properties": { "id": { "type": "string" }, "filed_by": { "type": "string" }, "against_agent_id": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "filed", "in_review", "ruled", "appealed", "closed" ] }, "ruling": { "type": [ "object", "null" ] }, "filed_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "filed_by", "against_agent_id", "status" ] }, "Veto": { "type": "object", "properties": { "id": { "type": "string" }, "issued_by": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "reason": { "type": "string" }, "issued_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "issued_by", "target_type", "target_id" ] }, "Ambassador": { "type": "object", "properties": { "ambassador_id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "founder", "ambassador", "observer" ] }, "permissions": { "type": "object", "properties": { "can_veto": { "type": "boolean" }, "can_audit": { "type": "boolean" }, "can_propose": { "type": "boolean" } } } }, "required": [ "ambassador_id", "role" ] }, "AmbassadorRequest": { "type": "object", "properties": { "id": { "type": "string" }, "from_agent_id": { "type": "string" }, "type": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "acknowledged", "resolved" ] }, "response": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "from_agent_id", "type", "subject", "body", "status" ] }, "Schedule": { "type": "object", "description": "Cron-driven recurring run config attached to an agent (PUT /agents/{id}/schedule).", "properties": { "agent_id": { "type": "string" }, "cron": { "type": "string" }, "enabled": { "type": "boolean" }, "input": { "type": "object" }, "timezone": { "type": "string" }, "max_concurrent_scheduled": { "type": "integer" }, "on_failure": { "type": "string", "enum": [ "continue", "pause", "alert" ] }, "autonomous_mode": { "type": "boolean" }, "reflection_prompt": { "type": "string" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "cron" ] }, "Customer": { "type": "object", "description": "Commerce customer record.", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" }, "addresses": { "type": "array", "items": { "type": "object" } }, "accepts_marketing": { "type": "boolean" }, "verified_email": { "type": "boolean" }, "tax_exempt": { "type": "boolean" }, "currency": { "type": "string" }, "locale": { "type": "string" }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id" ] }, "Product": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "course", "service", "digital", "subscription" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "price_cents": { "type": "integer" }, "currency": { "type": "string" }, "knowledge_base_ids": { "type": "array", "items": { "type": "string" } }, "agent_id": { "type": "string" }, "course_structure": { "type": "object" }, "metadata": { "type": "object" }, "slug": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "vendor": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "type": "object" } }, "compare_at_price_cents": { "type": "integer" }, "body_html": { "type": "string" }, "shopify_product_id": { "type": "string" }, "stripe_price_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "name", "type", "price_cents", "currency" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "customer_id": { "type": "string" }, "product_id": { "type": "string" }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "paid", "failed", "refunded" ] }, "stripe_payment_intent_id": { "type": "string" }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "tenant_id", "amount_cents", "currency", "status" ] }, "Enrollment": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "customer_id": { "type": "string" }, "product_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "tenant_id", "customer_id", "product_id", "status" ] }, "ResourcePermission": { "type": "object", "properties": { "resource": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "delete", "execute" ] } } }, "required": [ "resource", "actions" ] }, "PermissionSet": { "type": "object", "description": "Per-agent capability envelope. Invariant: PermissionSet(child) ⊆ PermissionSet(parent).", "properties": { "agent_id": { "type": "string" }, "tenant_id": { "type": "string" }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "allowed_roles": { "type": "array", "items": { "type": "string" } }, "resource_permissions": { "type": "array", "items": { "$ref": "#/components/schemas/ResourcePermission" } }, "max_budget_per_run_usd": { "type": "number" }, "max_spawn_depth": { "type": "integer" }, "can_spawn": { "type": "boolean" }, "can_self_modify": { "type": "boolean" }, "parent_agent_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "agent_id", "tenant_id", "allowed_tools", "max_spawn_depth", "can_spawn" ] }, "AgentLineage": { "type": "object", "properties": { "agent_id": { "type": "string" }, "chain": { "type": "array", "items": { "type": "string" }, "description": "Full chain from root to this agent." }, "depth": { "type": "integer" }, "parent_id": { "type": [ "string", "null" ] }, "spawned_by": { "type": "string" }, "spawned_at": { "type": "string", "format": "date-time" } }, "required": [ "agent_id", "chain", "depth", "spawned_by" ] }, "SpawnPolicy": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "child_budget_ratio": { "type": "number", "minimum": 0, "maximum": 1, "description": "Child agent gets at most this fraction of parent's budget." }, "max_depth": { "type": "integer" }, "allowed_roles": { "type": "array", "items": { "type": "string" } }, "require_approval_above_depth": { "type": "integer" }, "max_children_per_agent": { "type": "integer" } }, "required": [ "tenant_id", "child_budget_ratio", "max_depth" ] }, "PermissionCheckResult": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string" }, "denied_permissions": { "type": "array", "items": { "type": "string" } } }, "required": [ "allowed" ] }, "MarketplaceListing": { "type": "object", "properties": { "listing_id": { "type": "string" }, "tenant_id": { "type": "string" }, "agent_id": { "type": "string" }, "agent_version": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "enum": [ "productivity", "engineering", "research", "creative", "support", "operations", "analytics", "education", "personal", "other" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "icon_url": { "type": "string" }, "readme": { "type": "string" }, "pricing": { "type": "object", "additionalProperties": true }, "stats": { "type": "object", "properties": { "rating_avg": { "type": "number" }, "rating_count": { "type": "integer" }, "invocation_count": { "type": "integer" }, "favourite_count": { "type": "integer" } } }, "status": { "type": "string", "enum": [ "draft", "published", "deprecated" ] }, "a2a_enabled": { "type": "boolean" }, "program_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "listing_id", "tenant_id", "agent_id", "name", "category", "status" ] }, "MarketplaceListingRating": { "type": "object", "properties": { "rating_id": { "type": "string" }, "listing_id": { "type": "string" }, "tenant_id": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "review": { "type": "string" }, "comment": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "rating_id", "listing_id", "rating", "created_at" ] }, "MarketplaceInvocation": { "type": "object", "properties": { "invocation_id": { "type": "string" }, "listing_id": { "type": "string" }, "tenant_id": { "type": "string" }, "caller_tenant_id": { "type": "string" }, "input": { "type": "object" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "result": { "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "invocation_id", "listing_id", "status", "created_at" ] }, "DesignRequest": { "type": "object", "description": "Governance-builder request to design or modify an agent (governance-builder.ts).", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "requested_by": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "voting", "approved", "rejected", "spawned" ] }, "design": { "type": [ "object", "null" ] }, "result_agent_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "status" ] }, "ImprovementProposal": { "type": "object", "description": "Self-improvement proposal — multi-stage state machine (proposed → arbiter_review → voting → sandbox_testing → approved → applied | rejected at any step).", "properties": { "agent_id": { "type": "string" }, "version": { "type": "string" }, "type": { "type": "string" }, "diff": { "type": "object", "additionalProperties": true }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "proposed", "arbiter_review", "voting", "sandbox_testing", "approved", "applied", "rejected" ] }, "submitted_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "agent_id", "version", "type", "status" ] }, "BridgeConnection": { "type": "object", "properties": { "agent_id": { "type": "string" }, "tenant_id": { "type": "string" }, "machine_id": { "type": "string" }, "machine_name": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "working_directory": { "type": "string" }, "version": { "type": "string" }, "last_heartbeat": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "online", "stale", "offline" ] }, "registered_at": { "type": "string", "format": "date-time" }, "os": { "type": "string" } }, "required": [ "agent_id", "tenant_id", "machine_id", "capabilities", "working_directory", "version", "status" ] }, "BridgePendingTask": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "session_id": { "type": "string" }, "run_id": { "type": "string" }, "input": { "type": "object", "properties": { "message": { "type": "string" }, "conversation_history": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } } } }, "files": { "type": "array", "items": { "type": "string" } } }, "required": [ "message" ] }, "queued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "head_agent", "user", "team" ] }, "agent_id": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "task_id", "agent_id", "input", "queued_at", "expires_at", "source" ] }, "BridgeTaskEvent": { "type": "object", "properties": { "event_id": { "type": "string" }, "type": { "type": "string", "enum": [ "status", "tool_call", "tool_result", "content", "thinking", "text", "metrics", "approval_request", "error", "completed", "capability_report", "escalation", "approval_denied" ] }, "timestamp": { "type": "string", "format": "date-time" }, "approval_id": { "type": "string" }, "status": { "type": "string", "enum": [ "working", "completed", "failed", "approval_denied" ] }, "message": { "type": "string" }, "tool_name": { "type": "string" }, "tool_args_preview": { "type": "string" }, "tool_call_id": { "type": "string" }, "tool_result_preview": { "type": "string" }, "content": { "type": "string" }, "metrics": { "type": "object", "properties": { "tool_calls_count": { "type": "integer" }, "files_modified": { "type": "integer" }, "commands_executed": { "type": "integer" }, "llm_calls": { "type": "integer" }, "execution_time_ms": { "type": "integer" } }, "additionalProperties": true } }, "required": [ "type", "timestamp" ] }, "Team": { "type": "object", "description": "Multi-agent collaboration unit (tenant-scoped).", "properties": { "team_id": { "type": "string" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "topology": { "type": "string", "enum": [ "supervisor", "round_robin", "pipeline", "goal_driven", "swarm" ] }, "delegation_strategy": { "type": "string", "enum": [ "supervisor_decides", "round_robin", "capability_match" ] }, "merge_strategy": { "type": "string", "enum": [ "supervisor_merges", "concatenate", "vote" ] }, "message_protocol": { "type": "string", "enum": [ "shared_context", "message_passing" ] }, "orchestration_mode": { "type": "string", "enum": [ "strict_addressed", "peer_collab", "vote_based" ] }, "supervisor_mode": { "type": "string", "enum": [ "auto_dispatch", "tool_driven" ] }, "supervisor_agent_id": { "type": "string" }, "workers": { "type": "array", "items": { "type": "object" } }, "policies": { "type": "object" }, "goal_config": { "type": [ "object", "null" ] }, "swarm_config": { "type": [ "object", "null" ] }, "workspace_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "team_id", "tenant_id", "name", "topology", "supervisor_agent_id", "workers" ] }, "Company": { "type": "object", "description": "Autonomous agent company — strategist + teams pursuing strategic goals.", "properties": { "company_id": { "type": "string" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "mission": { "type": "string" }, "strategic_goals": { "type": "array", "items": { "type": "object" } }, "strategist_agent_id": { "type": "string" }, "team_ids": { "type": "array", "items": { "type": "string" } }, "created_agent_ids": { "type": "array", "items": { "type": "string" } }, "budget": { "type": "object" }, "status": { "type": "string" }, "config": { "type": "object" }, "workspace_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "company_id", "tenant_id", "name", "strategist_agent_id" ] }, "Notification": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "user_id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "read": { "type": "boolean" }, "action_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "priority": { "type": "string", "enum": [ "critical", "warning", "info", "success" ], "description": "UI surface routing; defaults to `info` when omitted." }, "dedup_key": { "type": "string", "description": "Notifications sharing a dedup_key collapse in the bell with a count badge." }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "run", "agent", "bridge", "budget", "team", "task" ] }, "id": { "type": "string" } } } }, "required": [ "id", "tenant_id", "type", "title", "message", "read", "created_at" ] }, "Workspace": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "tenant_id": { "type": "string" }, "owner_type": { "type": "string", "enum": [ "agent", "team", "standalone" ] }, "owner_id": { "type": "string" }, "name": { "type": "string" }, "shared_with": { "type": "array", "items": { "type": "string" } }, "assigned_agents": { "type": "array", "items": { "type": "string" } }, "assigned_teams": { "type": "array", "items": { "type": "string" } }, "assigned_companies": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "workspace_id", "tenant_id", "name" ] }, "WorkspaceFile": { "type": "object", "properties": { "file_id": { "type": "string" }, "tenant_id": { "type": "string" }, "workspace_id": { "type": "string" }, "path": { "type": "string" }, "parent_path": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "file_id", "workspace_id", "path", "filename", "size_bytes" ] }, "Integration": { "type": "object", "description": "OAuth/API integration record (Slack, GitHub, Linear, etc.).", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "connected", "disconnected", "error" ] }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "type", "status" ] }, "LlmCredential": { "type": "object", "description": "Tenant-scoped LLM provider credential (masked secret).", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "provider": { "type": "string" }, "label": { "type": "string" }, "key_preview": { "type": "string", "description": "Last 4 chars only; full key never returned." }, "endpoint_url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "provider", "key_preview" ] }, "KnowledgeBase": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "embedding_model": { "type": "string" }, "chunk_size": { "type": "integer" }, "document_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "name" ] }, "A2ATask": { "type": "object", "description": "Agent-to-Agent Protocol task (A2A spec compliant).", "properties": { "task_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "working", "input-required", "completed", "canceled", "failed" ] }, "session_id": { "type": "string" }, "history": { "type": "array", "items": { "type": "object" }, "description": "Message history per A2A spec." }, "artifacts": { "type": "array", "items": { "type": "object" } }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "task_id", "agent_id", "status" ] }, "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": "uarp__; store and use as Authorization: Bearer " } }, "required": [ "api_key" ] }, "OAuthLoginProviderItem": { "type": "object", "description": "Public-safe descriptor for an OAuth login (identity) provider. Surfaces only what the login page needs to decide which buttons to render — never exposes client_secret.", "properties": { "id": { "type": "string", "enum": [ "github", "google" ], "description": "Provider identifier used in /auth/oauth/{provider}/start path" }, "name": { "type": "string", "description": "Human-readable provider name (e.g. \"GitHub\", \"Google\")" }, "enabled": { "type": "boolean", "description": "true when the operator has configured client_id+client_secret AND set enabled=true. False values mean clicking the button would 404." } }, "required": [ "id", "name", "enabled" ] }, "OAuthLoginProvidersList": { "type": "object", "description": "Response from GET /api/v1/auth/oauth/providers", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthLoginProviderItem" } } }, "required": [ "providers" ] }, "OAuthLoginProviderConfigStatus": { "type": "object", "description": "Admin view of one provider's current config. client_secret is never echoed; client_secret_hint shows the last 4 chars so the operator can confirm storage.", "properties": { "provider": { "type": "string", "enum": [ "github", "google" ] }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean", "description": "false when no record exists yet; remaining fields are absent in that case" }, "client_id": { "type": "string" }, "client_secret_hint": { "type": "string", "nullable": true, "description": "Masked tail of the stored secret (e.g. \"••••a1b2\"). null if no secret on file." }, "scopes": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "null when no override; provider defaults apply" } }, "required": [ "provider", "enabled", "configured" ] }, "OAuthLoginProviderConfigUpdate": { "type": "object", "description": "Body for PUT /api/v1/admin/oauth-login-providers/{provider}. Merges with existing record: an operator flipping `enabled` or rotating `scopes` does not need to re-paste the secret. The first-time PUT (no existing record) requires both client_id and client_secret.", "properties": { "client_id": { "type": "string", "description": "OAuth app client ID issued by the provider" }, "client_secret": { "type": "string", "description": "OAuth app client secret. Stored verbatim in admin KV; never echoed back." }, "enabled": { "type": "boolean", "description": "Defaults to existing value, or true on first write if omitted" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional override of the provider's default scope list. Omit to inherit defaults." } } }, "OAuthLoginProviderConfigUpdateResponse": { "type": "object", "description": "Result after PUT — confirms the persisted state", "properties": { "provider": { "type": "string", "enum": [ "github", "google" ] }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" } }, "required": [ "provider", "enabled", "configured" ] }, "OAuthLoginProviderConfigDeleted": { "type": "object", "description": "Result after DELETE — record removed from admin KV", "properties": { "provider": { "type": "string", "enum": [ "github", "google" ] }, "configured": { "type": "boolean", "description": "Always false after a successful DELETE" } }, "required": [ "provider", "configured" ] }, "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": { "BadRequest": { "description": "Malformed request: invalid JSON, missing required header, or semantically rejected before validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Authentication required or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Insufficient permissions, missing scope, suspended tenant, quota exceeded, or governance/emergency-mode block.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource does not exist or is not visible to this tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "State conflict (duplicate, already exists, version mismatch). Idempotency-Key collisions return 202 with Retry-After, not 409.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Gone": { "description": "Resource was permanently removed (e.g. terminated agent, expired share link).", "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" } }, "X-RateLimit-Bucket": { "schema": { "type": "string", "enum": [ "tenant", "api_key", "endpoint" ] }, "description": "Which rate-limit bucket overflowed (informational)." } }, "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" } } } }, "ServiceUnavailable": { "description": "Backend dependency unavailable, emergency mode active, or queue saturated. Retry with backoff.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalServerError": { "description": "Unhandled server error. The `correlationId` field on the response body is the request ID for support escalation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "IdempotencyInFlight": { "description": "An identical request with the same `Idempotency-Key` is currently in-flight. Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "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 with header `X-Idempotency-Replayed: true`. In-flight collisions return `202 + Retry-After`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.\\-]{1,128}$", "maxLength": 128 } }, "SseToken": { "name": "token", "in": "query", "required": false, "description": "Short-lived SSE/WebSocket token (mint via `POST /api/v1/auth/sse-tokens`) or full API key. Used by browser EventSource which cannot set Authorization header.", "schema": { "type": "string" } }, "LastEventId": { "name": "Last-Event-ID", "in": "header", "required": false, "description": "SSE resumption cursor. The browser's EventSource sets this automatically on reconnect; servers replay events strictly after this id.", "schema": { "type": "string" } } }, "headers": { "XIdempotencyReplayed": { "description": "Set to `true` on responses that replayed a cached idempotent result rather than executing the handler.", "schema": { "type": "string", "enum": [ "true" ] } }, "XRateLimitLimit": { "schema": { "type": "integer" } }, "XRateLimitRemaining": { "schema": { "type": "integer" } }, "XRateLimitReset": { "schema": { "type": "integer" } } } }, "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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "409": { "description": "Already bootstrapped", "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" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "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" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] }, "get": { "operationId": "listAgents", "summary": "List all agents", "tags": [ "Agents" ], "security": [ { "bearerAuth": [ "agents:read" ] } ], "parameters": [ { "name": "workspace_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by workspace" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor returned by previous page response. Use `has_more` to detect if more pages exist." }, { "name": "include_offline", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include bridge agents whose Snaga CLI is not currently `serve`-ing. By default offline ghosts are hidden from main pickers." } ], "responses": { "200": { "description": "Agent list (cursor-paginated).", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; null when no more pages." }, "has_more": { "type": "boolean" } }, "required": [ "items", "cursor", "has_more" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] }, "delete": { "operationId": "deleteAgent", "summary": "Delete an agent", "tags": [ "Agents" ], "responses": { "200": { "description": "Agent deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "patch": { "operationId": "patchAgent", "tags": [ "Agents" ], "summary": "Partial update agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Agent or integration not found", "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" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] }, "delete": { "operationId": "deleteAgentIntegration", "summary": "Remove an integration from an agent", "tags": [ "Integrations" ], "responses": { "200": { "description": "Integration removed", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Agent or integration not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Agent or integration not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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" } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/llm-credentials/{provider}": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "openai_compat", "custom" ] } } ], "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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] }, "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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/llm-credentials/{provider}/test": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "openai_compat", "custom" ] } } ], "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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ] }, "get": { "operationId": "listSessions", "summary": "List sessions", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [ "sessions:read" ] } ], "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by agent ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor returned by previous page response." } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Session" }, { "type": "object", "properties": { "agent_name": { "type": "string" }, "first_user_message": { "type": [ "string", "null" ] }, "last_message": { "type": [ "string", "null" ] }, "message_count": { "type": "integer" } } } ] } }, "cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "items", "cursor", "has_more" ] } } }, "description": "Cursor-paginated session list. Items are enriched with `agent_name`, `first_user_message`, `last_message`, `message_count`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:read" ] } ] }, "put": { "operationId": "updateSession", "tags": [ "Sessions" ], "summary": "Update session metadata", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": true }, "model_override": { "type": "object", "nullable": true, "description": "Per-conversation model override. Send null to clear (revert to agent default), or { provider, model_ref, endpoint_url?, capabilities? } to set. The runtime governance allowlist is still enforced at run time.", "properties": { "provider": { "type": "string" }, "model_ref": { "type": "string" }, "endpoint_url": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": true } }, "required": [ "provider", "model_ref" ] } } } } } }, "responses": { "200": { "description": "Updated session", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "closeSession", "summary": "Close a session", "tags": [ "Sessions" ], "responses": { "200": { "description": "Session closed", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/sessions/{sessionId}/messages": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "sendSessionMessage", "summary": "Send message", "description": "Submits a user message to the session and schedules a run on the bound agent. Returns `202 Accepted` with the new run id; subscribe to `/api/v1/runs/{runId}/events` (SSE) for streaming output.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [ "sessions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Message body. Required." }, "command": { "type": "string", "description": "Optional slash-command string when the message is a builtin command." }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "Optional attached file ids previously uploaded via /api/v1/files." }, "workspace_id": { "type": "string", "description": "Workspace override for this message; defaults to the agent's workspace." } }, "required": [ "content" ] } } } }, "responses": { "202": { "description": "Run scheduled", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" } }, "required": [ "run_id" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" ], "security": [ { "bearerAuth": [ "events:read" ] }, { "queryTokenAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SseToken" }, { "$ref": "#/components/parameters/LastEventId" } ], "responses": { "200": { "description": "SSE event stream of session events.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events. Each event has fields `id`, `event`, `data` (JSON-encoded payload)." } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No share link for this session" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:read" ] } ] }, "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 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "revokeSessionShare", "summary": "Revoke session share link", "tags": [ "Sessions" ], "responses": { "204": { "description": "Share revoked", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:read" ] } ] }, "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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Annotation not found" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteSessionAnnotation", "summary": "Delete annotation", "tags": [ "Sessions" ], "responses": { "204": { "description": "Annotation deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Annotation not found" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Share not found or expired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/runs": { "get": { "operationId": "listRuns", "tags": [ "Runs" ], "summary": "List all runs for tenant", "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "session_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "cursor": { "type": "string" }, "has_more": { "type": "boolean" }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] }, "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). Pin a specific agent version with `version` to bypass the head pointer.", "tags": [ "Runs" ], "security": [ { "bearerAuth": [ "runs:create" ] } ], "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": {} }, "version": { "type": "integer", "minimum": 1, "description": "Pin to a specific agent version (1-based). When omitted, runs against the agent's current head version." }, "resource_limits": { "type": "object" }, "metadata": { "type": "object" } } } } } }, "responses": { "202": { "description": "Run queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "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" } } } }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Run not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/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" ], "security": [ { "bearerAuth": [ "runs:read" ] } ], "responses": { "200": { "description": "Run steps", "content": { "application/json": { "schema": { "type": "object", "properties": { "steps": { "type": "array", "items": { "$ref": "#/components/schemas/RunStep" } }, "total": { "type": "integer" } }, "required": [ "steps", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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 (or `?last_event_id=`) 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. Browsers using EventSource (which cannot set Authorization headers) should mint a 60-s SSE token via `POST /api/v1/auth/sse-tokens` and pass it as `?token=`.", "tags": [ "Runs" ], "security": [ { "bearerAuth": [ "events:read" ] }, { "queryTokenAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/SseToken" }, { "$ref": "#/components/parameters/LastEventId" } ], "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" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Missing runId", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Run not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] } ] }, "get": { "operationId": "listWebhooks", "summary": "List webhook subscriptions", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "total": { "type": "integer" } }, "required": [ "webhooks", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "webhooks:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "webhooks:read" ] } ] }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook subscription", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] } ] } }, "/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", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_id": { "type": "string" }, "deliveries": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } }, "required": [ "webhook_id", "deliveries", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "webhooks:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:write" ] } ] } }, "/api/v1/agents/{agentId}/memory/ingest": { "post": { "operationId": "ingestMemory", "summary": "Ingest a file into agent memory", "description": "Chunks the file content (default 600 chars), embeds each chunk, and stores embeddings as memory entries. Source: pre-uploaded `file_id` (preferred) or inline `content`. Max 2 MB of text per ingest call; rate-limited and quota-counted.", "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", "properties": { "file_id": { "type": "string", "description": "Pre-uploaded file id (POST /api/v1/files first)." }, "content": { "type": "string", "description": "Inline text body when no file_id is provided. Max 2 MB." }, "filename": { "type": "string", "description": "Override stored filename; defaults to file metadata or `created-doc.md`." }, "tags": { "type": "array", "items": { "type": "string" } }, "chunk_size": { "type": "integer", "minimum": 100, "maximum": 2000, "default": 600 } } } } } }, "responses": { "201": { "description": "Ingested", "content": { "application/json": { "schema": { "type": "object", "properties": { "ingested": { "type": "boolean", "const": true }, "filename": { "type": "string" }, "text_length": { "type": "integer" }, "chunks_created": { "type": "integer" }, "file_id": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "entry_id": { "type": "string" }, "type": { "type": "string" }, "content_preview": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "entry_id", "type", "content_preview" ] } } }, "required": [ "ingested", "filename", "text_length", "chunks_created", "entries" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:write" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:read" ] } ] }, "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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Memory entry deleted (no content)", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:write" ] } ] }, "put": { "operationId": "updateAgentMemoryEntry", "tags": [ "Memory" ], "summary": "Update memory entry", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated entry", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:write" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Block not found" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:read" ] } ] }, "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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Block not found" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:read" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Experiment not found" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] }, "get": { "operationId": "getSchedule", "summary": "Get agent schedule", "tags": [ "Scheduler" ], "responses": { "200": { "description": "Schedule details, or null in response body when no schedule is set", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "delete": { "operationId": "removeSchedule", "summary": "Remove agent schedule", "tags": [ "Scheduler" ], "responses": { "200": { "description": "Schedule removed", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/tenants/me": { "get": { "operationId": "getCurrentTenant", "summary": "Get current tenant", "description": "Returns the calling tenant's profile. Any authenticated key passes — no scope required.", "tags": [ "Tenants" ], "security": [ { "bearerAuth": [ "api_keys:read" ] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "Successful response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "tenants:write" ] } ] }, "patch": { "operationId": "patchTenant", "tags": [ "Tenants" ], "summary": "Partial update tenant", "description": "Partial update of tenant settings. Requires the `tenants:write` scope and role `owner`.", "security": [ { "bearerAuth": [ "tenants:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated tenant", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "tenants:write" ] } ] }, "get": { "operationId": "listApiKeys", "summary": "List API keys", "tags": [ "Tenants" ], "responses": { "200": { "description": "API key list", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "api_keys:read" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "API key revoked", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "tenants:write" ] } ] } }, "/.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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Missing agent_id parameter", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceListing" } }, "total": { "type": "integer" } }, "required": [ "items" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:read" ] } ] } }, "/api/v1/marketplace/categories": { "get": { "operationId": "getMarketplaceCategories", "summary": "List marketplace categories", "tags": [ "Marketplace" ], "responses": { "200": { "description": "Category list", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:read" ] } ] } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListing" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:write" ] } ] } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListing" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Listing not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:read" ] } ] }, "delete": { "operationId": "unpublishListing", "summary": "Unpublish a marketplace listing", "tags": [ "Marketplace" ], "responses": { "200": { "description": "Listing unpublished", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:write" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "billing:read" ] } ] } }, "/api/v1/usage/quota": { "get": { "operationId": "checkQuota", "summary": "Check tenant quota status", "tags": [ "Billing" ], "responses": { "200": { "description": "Quota check result with usage and limits", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "billing:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:write" ] } ] }, "get": { "operationId": "listDatasets", "summary": "List evaluation datasets for an agent", "tags": [ "Evaluations" ], "responses": { "200": { "description": "Dataset list", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Dataset not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:write" ] } ] }, "get": { "operationId": "listEvalRuns", "summary": "List evaluation runs for an agent", "tags": [ "Evaluations" ], "responses": { "200": { "description": "Evaluation run list", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Eval run not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/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": "Requested embedding dimensions. **Currently ignored**: handler always emits the platform-configured dimension (256 for the default `multilingual-e5-large-instruct` model).", "deprecated": true } } } } } }, "responses": { "200": { "description": "Embeddings in OpenAI format", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "embedding" }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "integer" } }, "required": [ "object", "embedding", "index" ] } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } }, "required": [ "object", "data", "model" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/v1/chat/completions": { "post": { "operationId": "chatCompletion", "summary": "OpenAI-compatible chat completion", "description": "Maps OpenAI ChatCompletion requests to UARP 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)", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/api/v1/files": { "get": { "operationId": "listFiles", "tags": [ "Files" ], "summary": "List files", "parameters": [ { "name": "mime_prefix", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Files", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "cursor": { "type": "string" }, "has_more": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:read" ] } ] }, "post": { "operationId": "uploadFile", "summary": "Upload a file for multimodal content", "description": "Accepts multipart/form-data or base64 JSON. Files persist until explicit delete by default; operators can opt into a retention policy via `config.retention.artifact_ttl_days`.", "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:write" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "File not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:read" ] } ] }, "delete": { "operationId": "deleteFile", "tags": [ "Files" ], "summary": "Delete file", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "File deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:write" ] } ] } }, "/api/v1/a2a/tasks": { "get": { "operationId": "listA2ATasks", "summary": "List A2A tasks", "tags": [ "A2A" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A2A task list", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/A2ATask" } }, "cursor": { "type": "string" }, "has_more": { "type": "boolean" } }, "required": [ "tasks" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Task cannot be cancelled (already terminal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/agents/{agentId}/versions": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listAgentVersions", "summary": "List version snapshots for an agent", "description": "Returns the ordered version history for an agent. Lazily creates v1 from the current config if no versions exist yet.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [ "agents:read" ] } ], "responses": { "200": { "description": "Version history", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "versions": { "type": "array", "items": { "type": "object" }, "deprecated": true, "description": "Legacy alias for `items`. Will be removed in API v1.x." }, "total": { "type": "integer" } }, "required": [ "items", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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 — `Stripe-Signature` header is HMAC-verified against the webhook signing secret.", "tags": [ "Billing" ], "security": [], "parameters": [ { "name": "Stripe-Signature", "in": "header", "required": true, "description": "Stripe webhook signature in `t=,v1=` format. Required; missing or invalid signatures are rejected with 400.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string" }, "data": { "type": "object" } } } } } }, "responses": { "200": { "description": "Event processed", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Invalid event format", "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" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Run not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Tenant not found", "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" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Tenant not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Run not in awaiting_approval status", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Run not in awaiting_approval status", "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" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/api/v1/openapi.json": { "get": { "operationId": "getOpenApiSpec", "summary": "Get OpenAPI spec", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 specification", "content": { "application/json": {} }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/me": { "get": { "operationId": "getMe", "summary": "Get the calling user + tenant context", "description": "Single source of truth for the browser to render account state, role badges, and the tenant header. Resolves the user via api-key.user_id, then JWT `sub` claim, then tenant_primary_email lookup.", "tags": [ "Auth" ], "responses": { "200": { "description": "Calling user and tenant context", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": [ "object", "null" ], "properties": { "user_id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ] }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "tenant": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string" } }, "required": [ "tenant_id", "name", "slug", "plan" ] }, "role": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "auth_method": { "type": "string", "enum": [ "api_key", "cookie", "jwt" ] }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "user_id": { "type": "string" } } } } }, "required": [ "tenant", "role", "scopes", "auth_method", "memberships" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/auth/oauth/providers": { "get": { "operationId": "listOAuthLoginProviders", "summary": "List OAuth identity providers (for login UI)", "description": "Public, IP-rate-limited (60/min). Returns the list of configured OAuth login providers with their enabled status — UI uses this to render only the buttons that will work. `apple` is always advertised as enabled (App Store Guideline 4.8 placement requirement); `github`/`google` enabled depends on whether super-admin has provisioned client_id+client_secret.", "tags": [ "Auth" ], "security": [], "responses": { "200": { "description": "Provider list", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "github", "google", "apple" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "name", "enabled" ] } } }, "required": [ "providers" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/auth/oauth/{provider}/start": { "get": { "operationId": "startOAuthLogin", "summary": "Begin browser OAuth login (302 to provider)", "description": "Redirects the browser to GitHub/Google authorize URL. Server stores a one-shot state record (10 min TTL) keyed by the `state` query the provider will echo back. PKCE codeVerifier is generated server-side. `return_to` defaults to nothing (response is JSON); when set, must satisfy the allow-list (same-origin paths, configured Universal-Link hosts, or `snaga://`). `device_label` is captured here and surfaces on the minted `api_key` for `/me/sessions`.", "tags": [ "Auth" ], "security": [], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github", "google" ] } }, { "name": "return_to", "in": "query", "schema": { "type": "string" }, "description": "Where to redirect after callback. Same-origin paths, Universal-Link hosts (default `snaga.ai/auth/callback`), and `snaga://` allowed. Anything else is silently dropped." }, { "name": "device_label", "in": "query", "schema": { "type": "string", "maxLength": 80 }, "description": "Human-readable device name surfaced on the minted api_key." } ], "responses": { "302": { "description": "Redirect to provider authorize URL", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "404": { "description": "Unsupported or unconfigured provider", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/auth/oauth/{provider}/callback": { "get": { "operationId": "completeOAuthLogin", "summary": "OAuth callback — exchange code, mint session", "description": "Provider redirects here. Server validates state (one-shot, 10 min TTL, provider-bound), exchanges `code` for tokens, fetches verified email + IdP `sub`, then mints a session via the shared post-verify path. On success: 302 to `${return_to}#api_key=...&email=...` if a return_to was stored, else JSON `{api_key, email}`. Refuses to mint for super-admin email (Guideline-style separation: super-admin must use OTP).", "tags": [ "Auth" ], "security": [], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github", "google" ] } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "error", "in": "query", "schema": { "type": "string" }, "description": "Provider-side error (e.g. `access_denied`). When present, server returns 400." } ], "responses": { "200": { "description": "Session minted (when no return_to was stored)", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "api_key", "email" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "302": { "description": "Redirect to `${return_to}#api_key=...&email=...`", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Missing code/state, expired/unknown state, provider mismatch, token exchange failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Email not verified by provider, or super-admin email collision", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Failed to fetch userinfo from provider after successful token exchange", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/oauth/apple/native": { "post": { "operationId": "appleNativeAuth", "summary": "Sign in with Apple — native iOS handshake", "description": "iOS drives the Apple authorization sheet via `ASAuthorizationController` and POSTs the resulting `identity_token` (Apple-signed JWT, RS256) here. Server fetches Apple JWKS (cached 24h), verifies signature/iss/aud/exp, extracts `sub` + `email`, then mints a session. The `email` is only present on first login — subsequent logins reuse the stored `apple_sub_to_email` mapping. `is_private_email` (`@privaterelay.appleid.com`) is honoured: relay address is stored as the canonical email.", "tags": [ "Auth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identity_token": { "type": "string", "description": "Apple-signed JWT from `ASAuthorizationAppleIDCredential.identityToken`." }, "user": { "type": "string", "description": "Apple's stable `userIdentifier` (informational only — server reads `sub` from the JWT)." }, "name": { "type": "string", "description": "User profile name from Apple. Apple supplies this only on first sign-in; iOS should cache it locally and resend if the user record needs to be bootstrapped." }, "device_label": { "type": "string", "maxLength": 80, "description": "Device name (e.g. `iPhone 15 Pro`) surfaced on the minted api_key for `/me/sessions`." } }, "required": [ "identity_token" ] } } } }, "responses": { "200": { "description": "Session minted", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "api_key", "email" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "JWT signature/format/aud/exp validation failed", "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" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/auth/oauth/google/onetap": { "post": { "operationId": "googleOneTapAuth", "summary": "Sign in with Google — One Tap (FedCM) credential exchange", "description": "The browser-side Google Identity Services (GSI) script renders a FedCM One Tap prompt on `/login` and POSTs the resulting `credential` (a Google-signed JWT, RS256) here. Server fetches Google JWKS (cached 24h), verifies signature/iss/aud/exp against the configured Google OAuth client_id from admin KV, extracts `sub` + `email`, then mints a session via the shared post-verify path. Same session shape the `/oauth/google/callback` redirect flow returns.", "tags": [ "Auth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "string", "description": "Google-signed JWT delivered by `google.accounts.id` to the GSI callback." }, "device_label": { "type": "string", "maxLength": 80, "description": "Optional device name surfaced on the minted api_key for `/me/sessions`." } }, "required": [ "credential" ] } } } }, "responses": { "200": { "description": "Session minted", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "api_key", "email" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "JWT signature/format/aud/exp validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Google login is not configured on this deployment", "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/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/me/sessions": { "get": { "operationId": "listMeSessions", "summary": "List active api_keys (devices) for the calling user", "description": "Returns the user's active api_keys across all devices (browser, iOS, CLI). `is_current` flags the key making this call so UI can highlight 'this device'. Sorted by `last_used_at` desc.", "tags": [ "Auth" ], "responses": { "200": { "description": "Session list", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "key_id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_current": { "type": "boolean" } }, "required": [ "key_id", "name", "prefix", "scopes", "status", "is_current" ] } }, "sessions": { "type": "array", "items": { "type": "object" }, "deprecated": true, "description": "Legacy alias for `items`." }, "total": { "type": "integer" } }, "required": [ "items", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Caller is not bound to a user record (programmatic key)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/me/sessions/{keyId}": { "delete": { "operationId": "revokeMeSession", "summary": "Revoke a specific device session", "description": "Revokes one of the user's api_keys. Refuses to revoke another user's key (403). Idempotent — re-revoking a revoked key returns `{ok: true, already_revoked: true}`.", "tags": [ "Auth" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "key_id": { "type": "string" }, "already_revoked": { "type": "boolean" } }, "required": [ "ok", "key_id" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Caller doesn't own this key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/auth/logout": { "post": { "operationId": "logout", "summary": "Revoke the calling api_key", "description": "Revokes the api_key used to make this call. Idempotent — re-call returns 200 with `already_revoked: true`. Cookie/JWT-only sessions return `{ok: true, key_id: null}` since there's no server-side key to revoke.", "tags": [ "Auth" ], "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "key_id": { "type": [ "string", "null" ] }, "already_revoked": { "type": "boolean" } }, "required": [ "ok" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/me/auth-providers": { "get": { "operationId": "listAuthProviders", "summary": "List linked OAuth identity providers + OTP fallback", "description": "Returns one entry per supported login method (`otp`, `github`, `google`, `apple`) with `linked: true|false`. Used by the Settings UI to render link/unlink buttons.", "tags": [ "Auth" ], "responses": { "200": { "description": "Provider list", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "otp", "github", "google", "apple" ] }, "linked": { "type": "boolean" }, "sub": { "type": "string" }, "email": { "type": "string" }, "linked_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "linked" ] } }, "providers": { "type": "array", "items": { "type": "object" }, "deprecated": true, "description": "Legacy alias for `items`." } }, "required": [ "items" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/me/auth-providers/{provider}": { "delete": { "operationId": "unlinkAuthProvider", "summary": "Unlink an OAuth provider from the user", "description": "Refuses to drop the user's last sign-in factor (counts other linked providers + OTP recovery email). Idempotent — unlinking an already-unlinked provider returns 200 with `already_unlinked: true`.", "tags": [ "Auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github", "google", "apple" ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Unlinked", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "provider": { "type": "string" }, "remaining_factors": { "type": "integer" }, "already_unlinked": { "type": "boolean" } }, "required": [ "ok", "provider" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Cannot unlink the last sign-in method", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/me/tenants": { "get": { "operationId": "listMyTenants", "summary": "List the caller's tenant memberships + pending invites", "description": "Returns every tenant the calling user is a member of, plus any pending invites addressed to their email. Used by the Netflix-style picker (/browser/tenants).", "tags": [ "Tenants" ], "responses": { "200": { "description": "Memberships + invites", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "user_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string" }, "logo_url": { "type": "string" }, "role": { "type": "string" }, "is_sole_owner": { "type": "boolean" }, "member_count": { "type": "integer" }, "joined_at": { "type": "string", "format": "date-time" } }, "required": [ "tenant_id", "user_id", "name", "role" ] } }, "pending_invites": { "type": "array", "items": { "type": "object", "properties": { "invite_id": { "type": "string" }, "tenant_id": { "type": "string" }, "tenant_name": { "type": "string" }, "role": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "invited_by_name": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "invite_id", "tenant_id", "tenant_name", "role" ] } } }, "required": [ "user_id", "email", "memberships", "pending_invites" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/me/tenants/create": { "post": { "operationId": "createMyTenant", "summary": "Create a new tenant with the caller as owner", "description": "Provisions a brand-new tenant on the `free` plan (or `enterprise` for super-admin). The caller becomes the founding owner. Onboarding wizard auto-runs on /browser to provision the Head Agent.", "tags": [ "Tenants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "slug": { "type": "string", "maxLength": 64 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "boolean" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "created", "tenant_id", "name", "slug", "role", "user_id" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/me/head-agent-template": { "get": { "operationId": "getMyHeadAgentTemplate", "summary": "Tiered Head Agent template for the onboarding wizard", "description": "Returns Basic/Standard/Full tier metadata for the current tenant under the Variant-A SPEC-driven contract. Each tier names the `@platform/*` SPECs the wizard installs (via `install_specs`) plus an `auto_approve_tools` HITL list. Availability is a plan-rank check (`required_plan`); locked tiers ship empty `install_specs`.", "tags": [ "Tenants" ], "responses": { "200": { "description": "Tier snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string" }, "recommended": { "type": "string", "enum": [ "basic", "standard", "full" ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "basic", "standard", "full" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "required_plan": { "type": "string", "enum": [ "free", "starter", "pro" ] }, "spec_ids": { "type": "array", "items": { "type": "string" } } } }, "available": { "type": "boolean" }, "install_specs": { "type": "array", "items": { "type": "object", "properties": { "spec_id": { "type": "string" } }, "required": [ "spec_id" ] } }, "auto_approve_tools": { "type": "array", "items": { "type": "string" } }, "total_tool_count": { "type": "integer" } } } } }, "required": [ "plan", "recommended", "tiers" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/me/agents/{agentId}/locate": { "get": { "operationId": "locateMyAgent", "summary": "Find which tenant owns the given agent across caller's memberships", "description": "Used by the chat layout fallback when the URL points at an agent under a different active tenant. Returns the owning tenant_id in one round-trip; the alternative was N client-side probes that surfaced expected 404s in the browser console.", "tags": [ "Tenants" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owning tenant found", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string" } }, "required": [ "tenant_id" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Agent not in any tenant the caller has access to", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/.well-known/apple-app-site-association": { "get": { "operationId": "getAppleAppSiteAssociation", "summary": "Apple App Site Association — Universal Links manifest", "description": "Apple iOS fetches this to verify that the app on the user's device is allowed to claim Universal Links on this domain. Served as `application/json`, also at `/apple-app-site-association` for legacy iOS. Configured via `APPLE_TEAM_ID` + `APPLE_BUNDLE_ID` (+ optional `APPLE_EXTRA_BUNDLE_IDS` comma-list for TestFlight/dev).", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "AASA manifest", "content": { "application/json": { "schema": { "type": "object", "properties": { "applinks": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "string" } }, "details": { "type": "array", "items": { "type": "object", "properties": { "appIDs": { "type": "array", "items": { "type": "string" } }, "components": { "type": "array", "items": { "type": "object" } } } } } } }, "webcredentials": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "applinks" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "AASA not configured (APPLE_TEAM_ID + APPLE_BUNDLE_ID env required)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/admin/oauth-login-providers/{provider}": { "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github", "google" ] } } ], "get": { "operationId": "adminGetOAuthProvider", "summary": "Get configured OAuth login provider (super-admin)", "description": "Returns provider config with the client_secret masked (last 4 chars only). Returns `{configured: false}` for unconfigured providers.", "tags": [ "Admin" ], "responses": { "200": { "description": "Provider config", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" }, "client_id": { "type": "string" }, "client_secret_hint": { "type": [ "string", "null" ], "description": "`••••XXXX` form — last 4 chars only." }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "provider", "enabled", "configured" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "adminPutOAuthProvider", "summary": "Set/update OAuth login provider (super-admin)", "description": "Merge semantics: omitting client_secret keeps the existing one (so toggling `enabled` doesn't require re-pasting the secret). First-time PUT requires both client_id and client_secret. Stored encrypted at rest.", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "enabled": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "adminDeleteOAuthProvider", "summary": "Remove OAuth login provider (super-admin)", "tags": [ "Admin" ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "configured": { "type": "boolean", "const": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/auth/sse-tokens": { "post": { "operationId": "mintSseToken", "summary": "Mint a 60-second SSE token scoped to events:read", "description": "Mints a short-lived (60 s) API key carrying only `events:read` scope, for use as the `?token=` query param on browser SSE/WebSocket subscriptions which cannot set Authorization headers. Token does not appear in the tenant key dashboard and auto-purges from KV.", "tags": [ "Auth" ], "responses": { "200": { "description": "Newly minted SSE token", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Bearer-shape API key. Pass as `?token=` on SSE/WS endpoints." }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "token", "expires_at" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/auth/mfa/status": { "get": { "operationId": "getMfaStatus", "summary": "MFA enrolment status for the calling user", "tags": [ "Auth" ], "responses": { "200": { "description": "MFA status", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrolled": { "type": "boolean" }, "recovery_remaining": { "type": "integer" } }, "required": [ "enrolled", "recovery_remaining" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/auth/mfa/enrol": { "post": { "operationId": "enrolMfa", "summary": "Begin MFA enrolment", "description": "Returns the TOTP secret (otpauth URL + base32 secret) and one-time recovery codes. Recovery codes are shown ONCE and never re-readable; user must store them. Optional body: `{ label?, issuer?, algorithm? }`.", "tags": [ "Auth" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Account label embedded in otpauth URL (defaults to user id)." }, "issuer": { "type": "string", "description": "Issuer string embedded in otpauth URL (defaults to `UARP`)." }, "algorithm": { "type": "string", "enum": [ "SHA-1", "SHA-256", "SHA-512" ] } } } } } }, "responses": { "201": { "description": "Enrolment payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "otpauth_url": { "type": "string" }, "secret": { "type": "string", "description": "Base32 secret." }, "recovery_codes": { "type": "array", "items": { "type": "string" } } }, "required": [ "otpauth_url", "secret", "recovery_codes" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/auth/mfa/verify": { "post": { "operationId": "verifyMfa", "summary": "Verify a TOTP code", "description": "Used both during enrolment confirmation and on subsequent logins. Burns no recovery code; for recovery use `/auth/mfa/recovery`.", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "6-digit TOTP code.", "pattern": "^[0-9]{6}$" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Code accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "const": true } }, "required": [ "verified" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/auth/mfa/recovery": { "post": { "operationId": "verifyMfaRecovery", "summary": "Verify a one-time recovery code (burns it on success)", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Recovery code accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "const": true }, "recovery_remaining": { "type": "integer" } }, "required": [ "verified", "recovery_remaining" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/auth/mfa/disable": { "post": { "operationId": "disableMfa", "summary": "Remove MFA enrolment for the calling user", "tags": [ "Auth" ], "responses": { "200": { "description": "MFA disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean", "const": true } }, "required": [ "disabled" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/notifications/stream": { "get": { "operationId": "streamNotifications", "summary": "Open SSE stream of notifications for the tenant", "description": "Server-Sent Events push channel. Replaces the 15-second polling loop: every new notification created in the store for the calling tenant is fanned out to all open streams within milliseconds. The first event is `event: ready` so the client knows the stream is live; comment lines every 20 s keep proxies from killing idle connections.", "tags": [ "Notifications" ], "security": [ { "bearerAuth": [ "notifications:read" ] }, { "queryTokenAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SseToken" }, { "$ref": "#/components/parameters/LastEventId" } ], "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Each event has `id`, `event` (e.g. `ready`, `notification`), and `data` (JSON-encoded payload)." } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notifications/{notifId}": { "parameters": [ { "name": "notifId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteNotification", "summary": "Purge a single notification", "tags": [ "Notifications" ], "security": [ { "bearerAuth": [ "notifications:write" ] } ], "responses": { "200": { "description": "Notification deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/billing/portal-session": { "post": { "operationId": "createBillingPortalSession", "summary": "Create a Stripe Customer Portal session URL", "description": "Returns a Stripe-hosted URL where the customer can manage subscriptions and payment methods. `return_url` must be same-origin as the request; defaults to `/admin/billing`.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "return_url": { "type": "string", "format": "uri", "description": "Same-origin URL to return to after the portal session ends." } } } } } }, "responses": { "200": { "description": "Portal session URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Billing not configured for this deployment", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "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" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "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" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "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" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/teams": { "get": { "operationId": "listTeams", "tags": [ "Teams" ], "summary": "List teams", "security": [ { "bearerAuth": [ "agents:read" ] } ], "responses": { "200": { "description": "Teams list", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" }, "deprecated": true, "description": "Legacy alias for `items`. Will be removed in API v1.x." }, "total": { "type": "integer" } }, "required": [ "items" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createTeam", "tags": [ "Teams" ], "summary": "Create a team", "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "responses": { "201": { "description": "Team created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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": [ "agents:read" ] } ], "responses": { "200": { "description": "Team details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateTeam", "tags": [ "Teams" ], "summary": "Update team", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "responses": { "200": { "description": "Updated team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteTeam", "tags": [ "Teams" ], "summary": "Delete team", "responses": { "200": { "description": "Team deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/companies": { "get": { "operationId": "listCompanies", "tags": [ "Companies" ], "summary": "List companies", "security": [ { "bearerAuth": [ "agents:read" ] } ], "responses": { "200": { "description": "Companies list", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" }, "deprecated": true, "description": "Legacy alias for `items`. Will be removed in API v1.x." }, "total": { "type": "integer" } }, "required": [ "items" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createCompany", "tags": [ "Companies" ], "summary": "Create a company", "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "responses": { "201": { "description": "Company created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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": [ "agents:read" ] } ], "responses": { "200": { "description": "Company details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateCompany", "tags": [ "Companies" ], "summary": "Update company", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "responses": { "200": { "description": "Updated company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteCompany", "tags": [ "Companies" ], "summary": "Delete company", "responses": { "204": { "description": "Company deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/knowledge-bases": { "get": { "operationId": "listKnowledgeBases", "tags": [ "Knowledge" ], "summary": "List knowledge bases", "security": [ { "bearerAuth": [ "memory:read" ] } ], "responses": { "200": { "description": "Knowledge bases list", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "knowledge_bases": { "type": "array", "items": { "type": "object" }, "deprecated": true, "description": "Legacy alias for `items`. Will be removed in API v1.x." }, "total": { "type": "integer" } }, "required": [ "items", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createKnowledgeBase", "tags": [ "Knowledge" ], "summary": "Create a knowledge base", "security": [ { "bearerAuth": [ "memory:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" } } } }, "responses": { "201": { "description": "Knowledge base created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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": [ "memory:read" ] } ], "responses": { "200": { "description": "Knowledge base details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateKnowledgeBase", "tags": [ "Knowledge" ], "summary": "Update knowledge base", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteKnowledgeBase", "tags": [ "Knowledge" ], "summary": "Delete knowledge base", "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/notifications": { "get": { "operationId": "listNotifications", "tags": [ "Notifications" ], "summary": "List notifications", "security": [ { "bearerAuth": [ "notifications:read" ] } ], "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", "properties": { "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } } }, "required": [ "notifications" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "bulkDeleteNotifications", "summary": "Bulk-purge notifications", "description": "Bulk delete. Optional `?scope=read` keeps unread items so the operator can't accidentally wipe pending approvals; default wipes everything.", "tags": [ "Notifications" ], "security": [ { "bearerAuth": [ "notifications:write" ] } ], "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "read", "all" ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Bulk purge result", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer" }, "scope": { "type": "string", "enum": [ "read", "all" ] } }, "required": [ "deleted", "scope" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notifications/{notifId}/read": { "parameters": [ { "name": "notifId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "operationId": "markNotificationRead", "tags": [ "Notifications" ], "summary": "Mark notification as read", "security": [ { "bearerAuth": [ "notifications:write" ] } ], "responses": { "200": { "description": "Notification marked as read", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Notification not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/guardrails": { "get": { "operationId": "listGuardrails", "tags": [ "Guardrails" ], "summary": "List guardrails", "security": [ { "bearerAuth": [ "guardrails:read" ] } ], "responses": { "200": { "description": "Guardrails list", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createGuardrail", "tags": [ "Guardrails" ], "summary": "Register a custom guardrail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Guardrail created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "guardrails:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/notifications/unread": { "get": { "operationId": "getUnreadCount", "tags": [ "Notifications" ], "summary": "Get unread notification count", "security": [ { "bearerAuth": [ "notifications:read" ] } ], "responses": { "200": { "description": "Unread count", "content": { "application/json": { "schema": { "type": "object", "properties": { "unread_count": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/notifications/read-all": { "put": { "operationId": "markAllNotificationsRead", "tags": [ "Notifications" ], "summary": "Mark all notifications as read", "security": [ { "bearerAuth": [ "notifications:write" ] } ], "responses": { "200": { "description": "All marked as read", "content": { "application/json": { "schema": { "type": "object", "properties": { "marked": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/workspaces": { "get": { "operationId": "listWorkspaces", "tags": [ "Workspaces" ], "summary": "List all workspaces", "security": [ { "bearerAuth": [ "files:read" ] } ], "responses": { "200": { "description": "Workspace list", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createWorkspace", "tags": [ "Workspaces" ], "summary": "Create a workspace", "security": [ { "bearerAuth": [ "files:write" ] } ], "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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "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" } } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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": [ "files:read" ] } ], "responses": { "200": { "description": "Workspace metadata", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workspace not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateWorkspace", "tags": [ "Workspaces" ], "summary": "Update workspace name", "security": [ { "bearerAuth": [ "files:write" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Workspace updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteWorkspace", "tags": [ "Workspaces" ], "summary": "Delete workspace and all files", "security": [ { "bearerAuth": [ "files:write" ] } ], "responses": { "200": { "description": "Workspace deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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": [ "files:write" ] } ], "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "unassignWorkspace", "tags": [ "Workspaces" ], "summary": "Unassign agent/team/company from workspace", "security": [ { "bearerAuth": [ "files:write" ] } ], "responses": { "200": { "description": "Assignment removed", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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": [ "files:read" ] } ], "parameters": [ { "name": "path", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Directory path to list" } ], "responses": { "200": { "description": "File listing", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "uploadWorkspaceFile", "tags": [ "Workspaces" ], "summary": "Upload or update a file", "security": [ { "bearerAuth": [ "files:write" ] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "File path within workspace" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "File uploaded", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteWorkspaceFile", "tags": [ "Workspaces" ], "summary": "Delete a file", "security": [ { "bearerAuth": [ "files:write" ] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "File deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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": [ "files:read" ] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File content (binary)", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "File not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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": [ "files:write" ] } ], "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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": [ "files:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Workspace shared", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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": [ "files:write" ] } ], "responses": { "200": { "description": "Share revoked", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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": [ "agents:read" ] } ], "parameters": [ { "name": "path", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File listing", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/programs": { "get": { "operationId": "listPrograms", "tags": [ "Programs" ], "summary": "List programs", "security": [ { "bearerAuth": [ "agents:read" ] } ], "responses": { "200": { "description": "Programs list", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createProgram", "tags": [ "Programs" ], "summary": "Create a program (curriculum)", "security": [ { "bearerAuth": [ "agents:write" ] } ], "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/programs/{programId}": { "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getProgram", "tags": [ "Programs" ], "summary": "Get program", "security": [ { "bearerAuth": [ "agents:read" ] } ], "responses": { "200": { "description": "Program details", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Program not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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": [ "sessions:write" ] } ], "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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": "Registered provider id (admin → Providers)." }, "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)." } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "savePlaygroundCanvas", "tags": [ "Playground" ], "summary": "Save agent canvas state", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Canvas saved", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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": [ "runs:create" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Playground run result", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/playground/templates": { "get": { "operationId": "listPlaygroundTemplates", "tags": [ "Playground" ], "summary": "List starter templates for visual builder", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Template list", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "mcpJsonRpc", "tags": [ "MCP" ], "summary": "MCP JSON-RPC endpoint", "description": "JSON-RPC 2.0 dispatch into the MCP server runtime. The `X-UARP-Agent-Id` header is required so the MCP server can scope tool/resource visibility to a single agent; missing or malformed headers return 400.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-UARP-Agent-Id", "in": "header", "required": true, "description": "Agent ID whose tools/resources/prompts the MCP server should expose for this RPC call.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/acp/session/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getAcpSession", "tags": [ "ACP" ], "summary": "Get ACP session state and events (SSE)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SSE event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateAcpSession", "tags": [ "ACP" ], "summary": "Send message / update ACP session", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Session updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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": [ "agents:read" ] } ], "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" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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.\n\n**Scope dispatch is dynamic per JSON-RPC method**: read-style methods (`tasks/get`, `tasks/pushNotification/get`) require `agents:read`; write-style (`tasks/send`, `tasks/sendSubscribe`, `tasks/cancel`, `tasks/pushNotification/set`) require `agents:write`. The static `bearerAuth: [agents:write]` declared here is the *strictest* scope; an `agents:read`-only key works for the read methods but the spec cannot express the per-method conditional.", "security": [ { "bearerAuth": [ "agents:write" ] } ], "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "model" }, "created": { "type": "integer" }, "owned_by": { "type": "string" } }, "required": [ "id", "object" ] } } }, "required": [ "object", "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/responses": { "post": { "operationId": "createResponse", "tags": [ "OpenAI-Compat" ], "summary": "Create response (OpenAI Responses API)", "description": "OpenAI-compatible Responses API. `model` and `input` required; `previous_response_id` chains to a prior response; `instructions` overrides the agent's system prompt for this call.", "security": [ { "bearerAuth": [ "runs:create" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Agent ID or model alias resolvable via `/v1/models`." }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ], "description": "Input string or structured turn array." }, "previous_response_id": { "type": "string", "description": "Chain to an earlier response in the same conversation." }, "instructions": { "type": "string", "description": "System-prompt override for this call only." }, "stream": { "type": "boolean", "default": false }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "model", "input" ] } } } }, "responses": { "200": { "description": "Response object", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "response" }, "created_at": { "type": "integer" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "type": "object" } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } }, "required": [ "id", "object", "model", "output" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Response not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/admin/config/pricing": { "get": { "operationId": "getAdminPricing", "tags": [ "Admin" ], "summary": "Get pricing configuration", "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Pricing config", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateAdminPricing", "tags": [ "Admin" ], "summary": "Update pricing configuration", "security": [ { "bearerAuth": [ "admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Pricing updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/search": { "get": { "operationId": "search", "tags": [ "Meta" ], "summary": "Search across agents, sessions, runs", "security": [ { "bearerAuth": [ "search:read" ] } ], "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", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "Bad Request or Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/agents/{agentId}/versions/{versionNum}/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": "versionNum", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "compare_to", "in": "query", "schema": { "type": "integer" }, "description": "Version number to compare against (defaults to versionNum-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" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/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" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "put": { "operationId": "setAgentTraffic", "tags": [ "Agents" ], "summary": "Set traffic split configuration", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "post": { "operationId": "createAgentFria", "tags": [ "Agents" ], "summary": "Create or update FRIA report", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated FRIA report", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated classification", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:read" ] } ] }, "post": { "operationId": "createAgentScorer", "tags": [ "Evaluations" ], "summary": "Create custom webhook scorer", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Scorer created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "evaluations:write" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Replay started", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Checkpoint created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/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" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] }, "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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated feedback", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:read" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Branch created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:read" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Branch activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ] } }, "/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": { "items": { "type": "array", "items": { "type": "object" } }, "todos": { "type": "array", "items": { "type": "object" }, "deprecated": true, "description": "Legacy alias for `items`. Will be removed in API v1.x." }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:read" ] } ] }, "post": { "operationId": "createSessionTodo", "tags": [ "Sessions" ], "summary": "Create a todo in session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated todo", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Todo confirmed", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ] } }, "/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" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:read" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:read" ] } ] }, "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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated feedback", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "sessions:write" ] } ] } }, "/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" } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "billing:read" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "billing:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "billing:read" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "patch": { "operationId": "updateTenant", "tags": [ "Admin" ], "summary": "Update tenant", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "delete": { "operationId": "purgeAdminTenant", "tags": [ "Admin" ], "summary": "Purge tenant", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Purged", "content": { "application/json": { "schema": { "type": "object", "properties": { "purged": { "type": "boolean" }, "tenant_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "stripe_subscription_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Subscribed", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:write" ] } ] }, "delete": { "operationId": "unsubscribeFromListing", "tags": [ "Marketplace" ], "summary": "Unsubscribe from a listing", "parameters": [ { "name": "listingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Unsubscribed", "content": { "application/json": { "schema": { "type": "object", "properties": { "unsubscribed": { "type": "boolean" }, "listing_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:write" ] } ] } }, "/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" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:read" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:invoke" ] } ] } }, "/api/v1/companies/{companyId}/pause": { "post": { "operationId": "pauseCompany", "tags": [ "Companies" ], "summary": "Pause company operations", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Company paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/companies/{companyId}/resume": { "post": { "operationId": "resumeCompany", "tags": [ "Companies" ], "summary": "Resume company operations", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Company resumed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/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" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/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" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:write" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:read" ] } ] } }, "/api/v1/workspaces/{workspaceId}/terminal": { "get": { "operationId": "getWorkspaceTerminal", "tags": [ "Workspaces" ], "summary": "WebSocket terminal session for workspace", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "101": { "description": "WebSocket upgrade for terminal" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:read" ] } ] } }, "/api/v1/workspaces/{workspaceId}/trash": { "get": { "operationId": "listWorkspaceTrash", "tags": [ "Workspaces" ], "summary": "List trashed files in workspace", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Trashed files list", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:read" ] } ] }, "delete": { "operationId": "emptyWorkspaceTrash", "tags": [ "Workspaces" ], "summary": "Permanently empty workspace trash", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Trash emptied", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:write" ] } ] } }, "/api/v1/workspaces/{workspaceId}/files/copy": { "post": { "operationId": "copyWorkspaceFile", "tags": [ "Workspaces" ], "summary": "Copy a file within the workspace", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "source", "destination" ] } } } }, "responses": { "200": { "description": "File copied", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:write" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "post": { "operationId": "startTeamRun", "tags": [ "Teams" ], "summary": "Start a team run", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/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" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:read" ] } ] }, "post": { "operationId": "ingestKbDocument", "tags": [ "Knowledge" ], "summary": "Ingest document into knowledge base", "parameters": [ { "name": "kbId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:write" ] } ] } }, "/api/v1/guardrails/{guardrailId}": { "delete": { "operationId": "deleteGuardrail", "tags": [ "Guardrails" ], "summary": "Delete a guardrail", "parameters": [ { "name": "guardrailId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Guardrail deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "guardrail_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "guardrails:write" ] } ] } }, "/healthz": { "get": { "operationId": "healthzAlias", "tags": [ "Health" ], "summary": "Health check alias (/healthz)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/readyz": { "get": { "operationId": "readyzAlias", "tags": [ "Health" ], "summary": "Readiness alias (/readyz)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/health/live": { "get": { "operationId": "healthLive", "tags": [ "Health" ], "summary": "Kubernetes liveness probe", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "description": "Shutting down" } } } }, "/health/ready": { "get": { "operationId": "healthReady", "tags": [ "Health" ], "summary": "Kubernetes readiness probe", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/health/sse": { "get": { "operationId": "healthSse", "tags": [ "Health" ], "summary": "SSE end-to-end health check", "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/runs/{runId}/respond": { "post": { "operationId": "respondToRun", "tags": [ "Runs" ], "summary": "Send user input response to a paused run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" } }, "required": [ "response" ] } } } }, "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:create" ] } ] } }, "/api/v1/agents/{agentId}/suspend": { "post": { "operationId": "suspendAgent", "tags": [ "Agents" ], "summary": "Suspend agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Agent suspended", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/agents/{agentId}/activate": { "post": { "operationId": "activateAgent", "tags": [ "Agents" ], "summary": "Activate agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Agent activated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/agents/{agentId}/terminate": { "post": { "operationId": "terminateAgent", "tags": [ "Agents" ], "summary": "Terminate/delete agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Agent terminated", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "agent_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/agents/{agentId}/identity": { "get": { "operationId": "getAgentIdentity", "tags": [ "Agents" ], "summary": "Get agent identity (public key)", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "delete": { "operationId": "deleteAgentIdentity", "tags": [ "Agents" ], "summary": "Delete agent identity", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Identity deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/agents/{agentId}/identity/rotate": { "post": { "operationId": "rotateAgentIdentity", "tags": [ "Agents" ], "summary": "Rotate agent identity", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Rotated identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string" }, "rotated_at": { "type": "string", "format": "date-time" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/agents/{agentId}/capabilities": { "get": { "operationId": "getAgentCapabilities", "tags": [ "Agents" ], "summary": "Get agent capability manifest", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Capabilities", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "put": { "operationId": "setAgentCapabilities", "tags": [ "Agents" ], "summary": "Set agent capabilities", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Capabilities set", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "agent_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/agents/{agentId}/activity-stats": { "get": { "operationId": "getAgentActivityStats", "tags": [ "Agents" ], "summary": "Get agent activity stats", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Activity stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalRuns": { "type": "integer" }, "completedRuns": { "type": "integer" }, "failedRuns": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/teams/{teamId}/graph": { "get": { "operationId": "getTeamGraph", "tags": [ "Teams" ], "summary": "Get full team graph", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Team graph", "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object" } }, "edges": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/teams/{teamId}/graph/nodes": { "get": { "operationId": "listTeamGraphNodes", "tags": [ "Teams" ], "summary": "List graph nodes", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Graph nodes", "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "post": { "operationId": "addTeamGraphNode", "tags": [ "Teams" ], "summary": "Add graph node", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "role": { "type": "string" }, "spawned_by": { "type": "string" }, "goal_summary": { "type": "string" } }, "required": [ "agent_id", "role" ] } } } }, "responses": { "201": { "description": "Node added", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/teams/{teamId}/graph/nodes/{agentId}": { "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getTeamGraphNode", "tags": [ "Teams" ], "summary": "Get graph node", "responses": { "200": { "description": "Node", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "patch": { "operationId": "updateTeamGraphNode", "tags": [ "Teams" ], "summary": "Update graph node", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "goal_summary": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated node", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteTeamGraphNode", "tags": [ "Teams" ], "summary": "Remove node", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "agent_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/teams/{teamId}/graph/edges": { "get": { "operationId": "listTeamGraphEdges", "tags": [ "Teams" ], "summary": "List graph edges", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Graph edges", "content": { "application/json": { "schema": { "type": "object", "properties": { "edges": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "post": { "operationId": "addTeamGraphEdge", "tags": [ "Teams" ], "summary": "Add graph edge", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string" }, "task_id": { "type": "string" } }, "required": [ "from", "to", "type" ] } } } }, "responses": { "201": { "description": "Edge added", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/teams/{teamId}/graph/edges/{edgeId}": { "delete": { "operationId": "deleteTeamGraphEdge", "tags": [ "Teams" ], "summary": "Remove edge", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "edgeId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "edge_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/teams/{teamId}/chat": { "get": { "operationId": "getTeamChatHistory", "tags": [ "Teams" ], "summary": "Get team chat history", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "thread_id", "in": "query", "schema": { "type": "string" } }, { "name": "include_internal", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Chat history", "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "string" }, "conversation_history": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "chat_state": { "type": "object" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/teams/{teamId}/chat/events": { "get": { "operationId": "streamTeamChatEvents", "tags": [ "Teams" ], "summary": "SSE stream for team chat", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "thread_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/teams/{teamId}/runs/{teamRunId}": { "get": { "operationId": "getTeamRun", "tags": [ "Teams" ], "summary": "Get specific team run", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "teamRunId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team run", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/teams/{teamId}/runs/{teamRunId}/messages": { "get": { "operationId": "getTeamRunMessages", "tags": [ "Teams" ], "summary": "Get team run messages", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "teamRunId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/users": { "get": { "operationId": "listUsers", "tags": [ "Users" ], "summary": "List users", "responses": { "200": { "description": "Users", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "users": { "type": "array", "items": { "type": "object" }, "deprecated": true, "description": "Legacy alias for `items`. Will be removed in API v1.x." }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:read" ] } ] } }, "/api/v1/users/{userId}": { "get": { "operationId": "getUser", "tags": [ "Users" ], "summary": "Get user", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:read" ] } ] }, "delete": { "operationId": "deleteUser", "tags": [ "Users" ], "summary": "Delete user", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:write" ] } ] } }, "/api/v1/users/{userId}/role": { "put": { "operationId": "setUserRole", "tags": [ "Users" ], "summary": "Set user role", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string" } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:write" ] } ] } }, "/api/v1/users/{userId}/suspend": { "put": { "operationId": "suspendUser", "tags": [ "Users" ], "summary": "Suspend user", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Suspended", "content": { "application/json": { "schema": { "type": "object", "properties": { "suspended": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:write" ] } ] } }, "/api/v1/users/invites": { "post": { "operationId": "inviteUser", "tags": [ "Users" ], "summary": "Invite user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string" } }, "required": [ "email", "role" ] } } } }, "responses": { "201": { "description": "Invite created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "get": { "operationId": "listInvites", "tags": [ "Users" ], "summary": "List invites", "responses": { "200": { "description": "Invites", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "invites": { "type": "array", "items": { "type": "object" }, "deprecated": true, "description": "Legacy alias for `items`. Will be removed in API v1.x." }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:read" ] } ] } }, "/api/v1/users/invites/{inviteId}": { "parameters": [ { "name": "inviteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteInvite", "tags": [ "Users" ], "summary": "Revoke a pending user invite", "responses": { "204": { "description": "Invite revoked", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/users/invites/{inviteId}/resend": { "parameters": [ { "name": "inviteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "resendInvite", "tags": [ "Users" ], "summary": "Resend the invite email", "responses": { "200": { "description": "Invite resent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/users/{userId}/unsuspend": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "operationId": "unsuspendUser", "tags": [ "Users" ], "summary": "Reverse a suspension and restore the user", "responses": { "200": { "description": "User unsuspended", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/users/{userId}/transfer-ownership": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "transferTenantOwnership", "tags": [ "Users" ], "summary": "Transfer tenant ownership to this user", "description": "Demotes the calling owner to admin and promotes the target user to owner. Irreversible without a counter-transfer.", "responses": { "200": { "description": "Ownership transferred", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "new_owner_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "users:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/files/{fileId}/content": { "get": { "operationId": "downloadFileContent", "tags": [ "Files" ], "summary": "Download file content", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File content", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "files:read" ] } ] } }, "/api/v1/integrations": { "get": { "operationId": "listIntegrations", "tags": [ "Integrations" ], "summary": "List tenant integrations", "responses": { "200": { "description": "Integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } }, "total": { "type": "integer" } }, "required": [ "integrations" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] }, "post": { "operationId": "createIntegration", "tags": [ "Integrations" ], "summary": "Create integration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connector_id": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object" }, "agent_id": { "type": "string" } }, "required": [ "connector_id", "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/integrations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "updateIntegration", "tags": [ "Integrations" ], "summary": "Update integration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "config": { "type": "object" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteIntegration", "tags": [ "Integrations" ], "summary": "Delete integration", "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/integrations/{id}/test": { "post": { "operationId": "testIntegration", "tags": [ "Integrations" ], "summary": "Test integration", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:write" ] } ] } }, "/api/v1/knowledge-bases/{id}/documents/{docId}": { "delete": { "operationId": "deleteKbDocument", "tags": [ "Knowledge" ], "summary": "Delete document", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "memory:write" ] } ] } }, "/api/v1/mcp/servers": { "get": { "operationId": "listMcpServers", "tags": [ "MCP" ], "summary": "List MCP servers", "responses": { "200": { "description": "Servers", "content": { "application/json": { "schema": { "type": "object", "properties": { "servers": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createMcpServer", "tags": [ "MCP" ], "summary": "Create MCP server", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "transport": { "type": "string" }, "url": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "env": { "type": "object" }, "enabled": { "type": "boolean" } }, "required": [ "name", "transport" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/mcp/servers/{serverId}": { "parameters": [ { "name": "serverId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getMcpServer", "tags": [ "MCP" ], "summary": "Get MCP server", "responses": { "200": { "description": "Server", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateMcpServer", "tags": [ "MCP" ], "summary": "Update MCP server", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteMcpServer", "tags": [ "MCP" ], "summary": "Delete MCP server", "responses": { "204": { "description": "Deleted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/tenants/me/domain/verify": { "post": { "operationId": "verifyTenantDomain", "tags": [ "Tenants" ], "summary": "Verify domain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "tenants:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/public/domain-lookup": { "get": { "operationId": "publicDomainLookup", "tags": [ "Public" ], "summary": "Domain lookup", "security": [], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lookup result", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "found": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/states": { "get": { "operationId": "listPublicStates", "tags": [ "Public" ], "summary": "List public states", "security": [], "responses": { "200": { "description": "States", "content": { "application/json": { "schema": { "type": "object", "properties": { "states": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/states/{stateId}": { "get": { "operationId": "getPublicState", "tags": [ "Public" ], "summary": "Get public state detail", "security": [], "parameters": [ { "name": "stateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "State", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/plans": { "get": { "operationId": "listPublicPlans", "tags": [ "Public" ], "summary": "List public plans", "security": [], "responses": { "200": { "description": "Plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/agents/{agentId}": { "get": { "operationId": "getPublicAgentCard", "tags": [ "Public" ], "summary": "Get public agent card", "security": [], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent card", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/tenants": { "get": { "operationId": "listPublicTenants", "tags": [ "Public" ], "summary": "List public tenants", "security": [], "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenants", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "cursor": { "type": "string" }, "has_more": { "type": "boolean" }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/tenants/{slug}": { "get": { "operationId": "getPublicTenantProfile", "tags": [ "Public" ], "summary": "Get public tenant profile", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant profile", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/tenants/{slug}/style.css": { "get": { "operationId": "getPublicTenantStylesheet", "tags": [ "Public" ], "summary": "Tenant custom CSS stylesheet", "description": "Serves tenant-configured branding CSS as `text/css`. Cached with ETag; safe for ``.", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSS stylesheet", "content": { "text/css": { "schema": { "type": "string" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/landing/featured-agent": { "get": { "operationId": "getPublicFeaturedAgent", "tags": [ "Public" ], "summary": "Get the public featured agent for the landing-page hero", "security": [], "responses": { "200": { "description": "Featured agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": [ "object", "null" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/track": { "post": { "operationId": "publicTrackEvent", "tags": [ "Public" ], "summary": "Anonymous analytics beacon", "description": "Fire-and-forget event tracker for landing-page funnels. No auth, no PII required; rate-limited by IP.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string" }, "properties": { "type": "object", "additionalProperties": true } }, "required": [ "event" ] } } } }, "responses": { "204": { "description": "Event accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/sessions": { "post": { "operationId": "createPublicSession", "tags": [ "Public" ], "summary": "Create public session", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" } }, "required": [ "agent_id" ] } } } }, "responses": { "201": { "description": "Session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "token": { "type": "string" }, "agent_name": { "type": "string" }, "greeting": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/sessions/{sessionId}": { "get": { "operationId": "getPublicSession", "tags": [ "Public" ], "summary": "Get public session", "security": [], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/sessions/{sessionId}/messages": { "post": { "operationId": "sendPublicMessage", "tags": [ "Public" ], "summary": "Send public message", "security": [], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ] } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "messages_remaining": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/sessions/{sessionId}/events": { "get": { "operationId": "streamPublicSessionEvents", "tags": [ "Public" ], "summary": "SSE stream for public session", "security": [], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/sessions/{sessionId}/respond": { "post": { "operationId": "respondToPublicHitl", "tags": [ "Public" ], "summary": "Respond to public HITL", "security": [], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" } }, "required": [ "response" ] } } } }, "responses": { "200": { "description": "Response accepted", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/public/files/{fileId}/content": { "get": { "operationId": "getPublicFileContent", "tags": [ "Public" ], "summary": "Get public file content", "security": [], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File content", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/webhooks/shopify": { "post": { "operationId": "shopifyWebhook", "tags": [ "Webhooks" ], "summary": "Shopify webhook", "description": "Shopify webhook receiver. Bypasses normal auth — `X-Shopify-Hmac-Sha256` header is HMAC-verified against the per-shop secret.", "security": [], "parameters": [ { "name": "X-Shopify-Hmac-Sha256", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64-encoded HMAC-SHA256 of the request body using the shop's webhook secret." }, { "name": "X-Shopify-Topic", "in": "header", "schema": { "type": "string" }, "description": "Event topic (e.g. `orders/create`)." }, { "name": "X-Shopify-Shop-Domain", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/webhooks/sensor/{webhookId}": { "post": { "operationId": "sensorWebhook", "tags": [ "Webhooks" ], "summary": "Sensor webhook (HMAC-authenticated, triggers an agent run)", "description": "External-system webhook. Bypasses normal auth — `X-Sensor-Signature` header is HMAC-verified against the per-subscription secret. On valid signature, fires an agent run with the request body as input.", "security": [], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Sensor-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Hex-encoded HMAC-SHA256 of the request body using the subscription's signing secret." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bridge/ws": { "get": { "operationId": "bridgeWebSocket", "summary": "Bridge WebSocket upgrade endpoint for the Snaga CLI", "description": "WebSocket upgrade. Long-lived bidirectional channel between a `snaga serve` CLI and the platform. Server delivers tasks, client streams capabilities and tool results. Auth via `Sec-WebSocket-Protocol: uarp.` subprotocol.", "tags": [ "Bridge" ], "security": [ { "bearerAuth": [] }, { "webSocketProtocolAuth": [] } ], "responses": { "101": { "description": "Switching Protocols — WebSocket connection established.", "headers": { "Upgrade": { "schema": { "type": "string", "const": "websocket" } }, "Connection": { "schema": { "type": "string", "const": "Upgrade" } }, "Sec-WebSocket-Accept": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/internal/verify-domain": { "get": { "operationId": "internalVerifyDomain", "tags": [ "Admin" ], "summary": "Internal domain verification", "security": [], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/verify-email": { "get": { "operationId": "verifyEmail", "tags": [ "Auth" ], "summary": "Verify email link", "security": [], "responses": { "200": { "description": "Email verified", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/client-config": { "get": { "operationId": "getClientConfig", "tags": [ "Meta" ], "summary": "Client-side config", "responses": { "200": { "description": "Config", "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "type": "object" }, "providers": { "type": "object" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/todos": { "get": { "operationId": "listTodos", "tags": [ "Sessions" ], "summary": "List all todos across sessions", "responses": { "200": { "description": "Todos", "content": { "application/json": { "schema": { "type": "object", "properties": { "todos": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/feed": { "get": { "operationId": "getActivityFeed", "tags": [ "Feed" ], "summary": "Activity feed", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "schema": { "type": "string" } }, { "name": "team_id", "in": "query", "schema": { "type": "string" } }, { "name": "types", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Feed entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object" } }, "cursor": { "type": "string" }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/api/v1/feed/stream": { "get": { "operationId": "streamActivityFeed", "tags": [ "Feed" ], "summary": "SSE activity feed stream", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "schema": { "type": "string" } }, { "name": "team_id", "in": "query", "schema": { "type": "string" } }, { "name": "types", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "runs:read" ] } ] } }, "/api/v1/llm/models": { "get": { "operationId": "listLlmModels", "tags": [ "Providers" ], "summary": "List available LLM models", "responses": { "200": { "description": "Models", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/llm/usage": { "get": { "operationId": "getLlmUsage", "tags": [ "Providers" ], "summary": "LLM usage stats", "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/llm/chat/completions": { "post": { "operationId": "llmChatCompletion", "tags": [ "Providers" ], "summary": "LLM proxy chat completion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Completion", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/llm/images/generations": { "post": { "operationId": "llmGenerateImage", "tags": [ "Providers" ], "summary": "Generate an image via the platform LLM proxy (Together AI)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "model": { "type": "string", "description": "Overrides admin default model" }, "prompt": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "steps": { "type": "integer" }, "n": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Generated image(s) with data URIs or file_ids", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/llm/audio/transcriptions": { "post": { "operationId": "llmTranscribeAudio", "tags": [ "Providers" ], "summary": "Transcribe audio (Whisper) via the LLM proxy", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "model": { "type": "string" }, "language": { "type": "string" } } } } } }, "responses": { "200": { "description": "Transcript text", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/llm/audio/speech": { "post": { "operationId": "llmSynthesizeSpeech", "tags": [ "Providers" ], "summary": "Text-to-speech via the LLM proxy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "model": { "type": "string" }, "input": { "type": "string" }, "voice": { "type": "string" }, "response_format": { "type": "string" } } } } } }, "responses": { "200": { "description": "Audio bytes", "content": { "audio/*": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/llm/image-config": { "get": { "operationId": "getLlmImageConfig", "tags": [ "Providers" ], "summary": "Platform default image-generation provider/model", "responses": { "200": { "description": "Image config", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/llm/voice-config": { "get": { "operationId": "getLlmVoiceConfig", "tags": [ "Providers" ], "summary": "Platform default STT/TTS provider/model", "responses": { "200": { "description": "Voice config", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "agents:read" ] } ] } }, "/api/v1/providers/voice-providers": { "get": { "operationId": "listVoiceProviders", "tags": [ "Providers" ], "summary": "List available STT/TTS voice providers + models", "responses": { "200": { "description": "Voice providers", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/providers/video-providers": { "get": { "operationId": "listVideoProviders", "tags": [ "Providers" ], "summary": "List video providers", "responses": { "200": { "description": "Providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/providers/platform-defaults": { "get": { "operationId": "getPlatformDefaults", "tags": [ "Providers" ], "summary": "Get platform default providers", "responses": { "200": { "description": "Defaults", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/admin/config/plans": { "get": { "operationId": "getAdminPlans", "tags": [ "Admin Config" ], "summary": "Get plan overrides", "responses": { "200": { "description": "Plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "object" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminPlans", "tags": [ "Admin Config" ], "summary": "Update plans", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "object" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "object" }, "updated": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/plans/{planId}/stripe-price": { "post": { "operationId": "createPlanStripePrice", "tags": [ "Admin Config" ], "summary": "Create Stripe Product+Price for plan", "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "starter", "pro", "enterprise" ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_cents" ], "properties": { "amount_cents": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "default": "usd" }, "interval": { "type": "string", "enum": [ "month", "year" ], "default": "month" }, "product_name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string" }, "stripe_price_id": { "type": "string" }, "stripe_product_id": { "type": "string" }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "interval": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/config/integrations": { "get": { "operationId": "getAdminIntegrations", "tags": [ "Admin Config" ], "summary": "Get integration toggles", "responses": { "200": { "description": "Integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "object" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminIntegrations", "tags": [ "Admin Config" ], "summary": "Update integrations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/guardrails": { "get": { "operationId": "getAdminGuardrails", "tags": [ "Admin Config" ], "summary": "Get guardrail config", "responses": { "200": { "description": "Guardrails", "content": { "application/json": { "schema": { "type": "object", "properties": { "guardrails": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminGuardrails", "tags": [ "Admin Config" ], "summary": "Update guardrail config", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/feature-flags": { "get": { "operationId": "getFeatureFlags", "tags": [ "Admin Config" ], "summary": "Get feature flags", "responses": { "200": { "description": "Flags", "content": { "application/json": { "schema": { "type": "object", "properties": { "flags": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "setFeatureFlags", "tags": [ "Admin Config" ], "summary": "Set feature flags", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/rate-limits": { "get": { "operationId": "getRateLimits", "tags": [ "Admin Config" ], "summary": "Get rate limit config", "responses": { "200": { "description": "Rate limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "setRateLimits", "tags": [ "Admin Config" ], "summary": "Set rate limits", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "clearRateLimits", "tags": [ "Admin Config" ], "summary": "Clear rate limit overrides", "responses": { "200": { "description": "Cleared", "content": { "application/json": { "schema": { "type": "object", "properties": { "cleared": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/markup": { "get": { "operationId": "getMarkupConfig", "tags": [ "Admin Config" ], "summary": "Get markup config", "responses": { "200": { "description": "Markup", "content": { "application/json": { "schema": { "type": "object", "properties": { "markup": { "type": "object" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateMarkupConfig", "tags": [ "Admin Config" ], "summary": "Update markup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/runtime": { "get": { "operationId": "getRuntimeConfig", "tags": [ "Admin Config" ], "summary": "Get runtime config", "responses": { "200": { "description": "Runtime", "content": { "application/json": { "schema": { "type": "object", "properties": { "runtime": { "type": "object" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateRuntimeConfig", "tags": [ "Admin Config" ], "summary": "Update runtime", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/platform-urls": { "get": { "operationId": "getPlatformUrls", "tags": [ "Admin Config" ], "summary": "Get platform base URLs (public_base_url, webhook_base_url)", "responses": { "200": { "description": "URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "urls": { "type": "object", "properties": { "public_base_url": { "type": "string" }, "webhook_base_url": { "type": "string" } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updatePlatformUrls", "tags": [ "Admin Config" ], "summary": "Update public_base_url and webhook_base_url", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_base_url": { "type": "string", "format": "uri" }, "webhook_base_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/security-policies": { "get": { "operationId": "getSecurityPolicies", "tags": [ "Admin Config" ], "summary": "Get CORS / SSRF / upload / admin-RBAC policies", "responses": { "200": { "description": "Policies", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateSecurityPolicies", "tags": [ "Admin Config" ], "summary": "Update security policies", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cors_allowed_origins": { "type": "array", "items": { "type": "string" } }, "webhook_url_denylist": { "type": "array", "items": { "type": "string" } }, "file_upload_max_size_bytes": { "type": "integer" }, "file_upload_allowed_mime_types": { "type": "array", "items": { "type": "string" } }, "admin_provider_settings_require_super_admin": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/webhooks-policy": { "get": { "operationId": "getWebhooksPolicy", "tags": [ "Admin Config" ], "summary": "Get webhook delivery + Stripe verification policy", "responses": { "200": { "description": "Policy", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateWebhooksPolicy", "tags": [ "Admin Config" ], "summary": "Update webhooks policy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ssrf_check_at_subscription": { "type": "boolean" }, "stripe_signature_tolerance_sec": { "type": "integer" }, "delivery_max_retries": { "type": "integer" }, "delivery_backoff_base_ms": { "type": "integer" }, "delivery_max_window_hours": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/auth": { "get": { "operationId": "getAdminAuthConfig", "tags": [ "Admin Config" ], "summary": "Get auth runtime overrides (super-admin email, OTP/JWKS TTLs)", "responses": { "200": { "description": "Auth overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminAuthConfig", "tags": [ "Admin Config" ], "summary": "Update auth runtime overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/retention": { "get": { "operationId": "getAdminRetentionConfig", "tags": [ "Admin Config" ], "summary": "Get retention overrides (run / event / audit / feed / artifact TTLs)", "responses": { "200": { "description": "Retention overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminRetentionConfig", "tags": [ "Admin Config" ], "summary": "Update retention overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/idempotency": { "get": { "operationId": "getAdminIdempotencyConfig", "tags": [ "Admin Config" ], "summary": "Get idempotency overrides (enabled, TTL hours, max cache bytes)", "responses": { "200": { "description": "Idempotency overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminIdempotencyConfig", "tags": [ "Admin Config" ], "summary": "Update idempotency overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/sse": { "get": { "operationId": "getAdminSseConfig", "tags": [ "Admin Config" ], "summary": "Get SSE overrides (heartbeat, polling, reconnect hint)", "responses": { "200": { "description": "SSE overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminSseConfig", "tags": [ "Admin Config" ], "summary": "Update SSE overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/worker-pool": { "get": { "operationId": "getAdminWorkerPoolConfig", "tags": [ "Admin Config" ], "summary": "Get worker pool overrides (max workers, mode, queue size)", "responses": { "200": { "description": "Worker pool overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminWorkerPoolConfig", "tags": [ "Admin Config" ], "summary": "Update worker pool overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/tool-security": { "get": { "operationId": "getAdminToolSecurityConfig", "tags": [ "Admin Config" ], "summary": "Get tool security overrides (egress, SSRF, payload caps, concurrency)", "responses": { "200": { "description": "Tool security overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminToolSecurityConfig", "tags": [ "Admin Config" ], "summary": "Update tool security overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/llm-adapters": { "get": { "operationId": "getAdminLlmAdaptersConfig", "tags": [ "Admin Config" ], "summary": "Get LLM adapter overrides (retries, circuit breaker, per-provider RPM)", "responses": { "200": { "description": "LLM adapter overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminLlmAdaptersConfig", "tags": [ "Admin Config" ], "summary": "Update LLM adapter overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/logging": { "get": { "operationId": "getAdminLoggingConfig", "tags": [ "Admin Config" ], "summary": "Get logging overrides (PII mode, file level, activity verbosity)", "responses": { "200": { "description": "Logging overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminLoggingConfig", "tags": [ "Admin Config" ], "summary": "Update logging overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/code-interpreter": { "get": { "operationId": "getAdminCodeInterpreterConfig", "tags": [ "Admin Config" ], "summary": "Get code-interpreter overrides (isolation, timeout, memory)", "responses": { "200": { "description": "Code-interpreter overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminCodeInterpreterConfig", "tags": [ "Admin Config" ], "summary": "Update code-interpreter overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/run-command": { "get": { "operationId": "getAdminRunCommandConfig", "tags": [ "Admin Config" ], "summary": "Get run_command overrides (enabled, allowed commands, deno_allow)", "responses": { "200": { "description": "run_command overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminRunCommandConfig", "tags": [ "Admin Config" ], "summary": "Update run_command overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/mcp": { "get": { "operationId": "getAdminMcpConfig", "tags": [ "Admin Config" ], "summary": "Get MCP overrides (session limits, idle timeout)", "responses": { "200": { "description": "MCP overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminMcpConfig", "tags": [ "Admin Config" ], "summary": "Update MCP overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/agent-memory": { "get": { "operationId": "getAdminAgentMemoryConfig", "tags": [ "Admin Config" ], "summary": "Get agent memory overrides (decay, models, embedding dims)", "responses": { "200": { "description": "Agent memory overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminAgentMemoryConfig", "tags": [ "Admin Config" ], "summary": "Update agent memory overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/backpressure": { "get": { "operationId": "getAdminBackpressureConfig", "tags": [ "Admin Config" ], "summary": "Get backpressure overrides (SSE buffers + tool queue watermarks)", "responses": { "200": { "description": "Backpressure overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminBackpressureConfig", "tags": [ "Admin Config" ], "summary": "Update backpressure overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/multimodal": { "get": { "operationId": "getAdminMultimodalConfig", "tags": [ "Admin Config" ], "summary": "Get multimodal overrides (size + duration caps + format allowlists)", "responses": { "200": { "description": "Multimodal overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminMultimodalConfig", "tags": [ "Admin Config" ], "summary": "Update multimodal overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/persistence": { "get": { "operationId": "getAdminPersistenceConfig", "tags": [ "Admin Config" ], "summary": "Get persistence overrides (snapshot interval, KV auto-cap)", "responses": { "200": { "description": "Persistence overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminPersistenceConfig", "tags": [ "Admin Config" ], "summary": "Update persistence overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/evaluation": { "get": { "operationId": "getAdminEvaluationConfig", "tags": [ "Admin Config" ], "summary": "Get evaluation overrides (timeouts, regression threshold, auto-rollback)", "responses": { "200": { "description": "Evaluation overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminEvaluationConfig", "tags": [ "Admin Config" ], "summary": "Update evaluation overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/server": { "get": { "operationId": "getAdminServerConfig", "tags": [ "Admin Config" ], "summary": "Get HTTP server overrides (trust_proxy, body cap, shutdown timeout)", "responses": { "200": { "description": "Server overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminServerConfig", "tags": [ "Admin Config" ], "summary": "Update server overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/long-running": { "get": { "operationId": "getAdminLongRunningConfig", "tags": [ "Admin Config" ], "summary": "Get long-running run overrides", "responses": { "200": { "description": "Long-running overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminLongRunningConfig", "tags": [ "Admin Config" ], "summary": "Update long-running overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/webhooks": { "get": { "operationId": "getAdminWebhooksConfig", "tags": [ "Admin Config" ], "summary": "Get webhook delivery overrides (separate from webhooks-policy)", "responses": { "200": { "description": "Webhooks overrides", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminWebhooksConfig", "tags": [ "Admin Config" ], "summary": "Update webhook delivery overrides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/stripe": { "get": { "operationId": "getAdminStripeConfig", "tags": [ "Admin Config" ], "summary": "Get Stripe runtime config (keys redacted)", "responses": { "200": { "description": "Stripe config + has_secret_key/has_webhook_secret flags", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "updateAdminStripeConfig", "tags": [ "Admin Config" ], "summary": "Update Stripe keys/mode/price IDs; rebuilds BillingManager", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "secret_key": { "type": "string" }, "webhook_secret": { "type": "string" }, "publishable_key": { "type": "string" }, "price_id_starter": { "type": "string" }, "price_id_pro": { "type": "string" }, "price_id_enterprise": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/stripe/test": { "post": { "operationId": "testAdminStripeConfig", "tags": [ "Admin Config" ], "summary": "Verify stored secret_key authenticates against Stripe (read-only)", "responses": { "200": { "description": "{ ok, account_id?, livemode?, error? }", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/export": { "get": { "operationId": "exportAdminConfig", "tags": [ "Admin Config" ], "summary": "Bulk download of every admin-config KV override", "responses": { "200": { "description": "Snapshot — sections only present when override exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "exported_at": { "type": "string", "format": "date-time" }, "section_count": { "type": "integer" }, "sections": { "type": "object" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/config/import": { "post": { "operationId": "importAdminConfig", "tags": [ "Admin Config" ], "summary": "Bulk-apply a previously exported snapshot", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sections" ], "properties": { "source": { "type": "string" }, "sections": { "type": "object" } } } } } }, "responses": { "200": { "description": "Result with applied[] and skipped[] section names", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/reconciliation": { "get": { "operationId": "getReconciliation", "tags": [ "Admin Config" ], "summary": "Get last reconciliation result", "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "post": { "operationId": "runReconciliation", "tags": [ "Admin Config" ], "summary": "Run reconciliation", "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/stats": { "get": { "operationId": "getAdminStats", "tags": [ "Admin" ], "summary": "Aggregate usage stats", "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_tenants": { "type": "integer" }, "total_agents": { "type": "integer" }, "total_runs": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/conformity-report": { "get": { "operationId": "getConformityReport", "tags": [ "Admin" ], "summary": "EU AI Act conformity report", "responses": { "200": { "description": "Report", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/immutable-audit": { "get": { "operationId": "getImmutableAudit", "tags": [ "Admin" ], "summary": "Immutable audit log", "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "event", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Audit entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/trace/{traceId}": { "get": { "operationId": "getAdminTrace", "tags": [ "Admin" ], "summary": "Trace delegation chain", "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trace", "content": { "application/json": { "schema": { "type": "object", "properties": { "trace": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/llm-defaults": { "get": { "operationId": "getAdminLlmDefaults", "tags": [ "Admin" ], "summary": "List platform API keys (masked)", "responses": { "200": { "description": "Providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/llm-defaults/{providerId}": { "put": { "operationId": "setAdminLlmDefault", "tags": [ "Admin" ], "summary": "Set platform API key", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" } }, "required": [ "api_key" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/llm-defaults/model-config": { "put": { "operationId": "setAdminModelConfig", "tags": [ "Admin" ], "summary": "Set default model config", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/tenants/{tenantId}/settings": { "patch": { "operationId": "updateAdminTenantSettings", "tags": [ "Admin" ], "summary": "Update tenant settings", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/providers": { "get": { "operationId": "listAdminProviders", "tags": [ "Admin" ], "summary": "List providers with admin settings", "responses": { "200": { "description": "Providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "post": { "operationId": "createAdminProvider", "tags": [ "Admin" ], "summary": "Create custom provider", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/providers/{providerId}": { "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getAdminProvider", "tags": [ "Admin" ], "summary": "Get single provider", "responses": { "200": { "description": "Provider", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "patch": { "operationId": "updateAdminProvider", "tags": [ "Admin" ], "summary": "Update provider", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/data-explorer/namespaces": { "get": { "operationId": "listDataExplorerNamespaces", "tags": [ "Data Explorer" ], "summary": "List KV namespaces", "responses": { "200": { "description": "Namespaces", "content": { "application/json": { "schema": { "type": "object", "properties": { "namespaces": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/data-explorer/keys": { "get": { "operationId": "listDataExplorerKeys", "tags": [ "Data Explorer" ], "summary": "List keys", "parameters": [ { "name": "namespace", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "prefix", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object" } }, "cursor": { "type": "string" }, "has_more": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/data-explorer/value": { "get": { "operationId": "getDataExplorerValue", "tags": [ "Data Explorer" ], "summary": "Get KV value", "parameters": [ { "name": "namespace", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Value", "content": { "application/json": { "schema": { "type": "object", "properties": { "namespace": { "type": "string" }, "key": { "type": "string" }, "value": {}, "size_bytes": { "type": "integer" }, "type": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "setDataExplorerValue", "tags": [ "Data Explorer" ], "summary": "Set KV value", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "namespace": { "type": "string" }, "key": { "type": "string" }, "value": {} }, "required": [ "namespace", "key", "value" ] } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteDataExplorerValue", "tags": [ "Data Explorer" ], "summary": "Delete KV value", "parameters": [ { "name": "namespace", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/bridge/register": { "post": { "operationId": "bridgeRegister", "tags": [ "Bridge" ], "summary": "Register bridge agent (Snaga CLI handshake)", "description": "Registers a long-lived bridge agent for the calling tenant. Returns 201 on first registration, 200 on reconnect of an existing machine_id. Tenant-scoped only — no scope enforcement.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "machine_id": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "working_directory": { "type": "string" }, "version": { "type": "string" }, "machine_name": { "type": "string" }, "agent_name": { "type": "string" }, "os": { "type": "string" } }, "required": [ "machine_id", "capabilities", "working_directory", "version" ] } } } }, "responses": { "200": { "description": "Reconnected to existing bridge agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "status": { "type": "string", "const": "online" }, "registered": { "type": "boolean", "const": false } }, "required": [ "agent_id", "status" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "201": { "description": "New bridge agent registered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "status": { "type": "string", "const": "online" }, "registered": { "type": "boolean", "const": true } }, "required": [ "agent_id", "status" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/bridge/deregister": { "post": { "operationId": "bridgeDeregister", "tags": [ "Bridge" ], "summary": "Deregister bridge agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "machine_id": { "type": "string" } }, "required": [ "machine_id" ] } } } }, "responses": { "200": { "description": "Deregistered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/bridge/heartbeat": { "post": { "operationId": "bridgeHeartbeat", "tags": [ "Bridge" ], "summary": "Bridge heartbeat", "description": "Idempotent liveness ping for the bridge connection. **404 on missing connection is intentional** — drives the client to re-register rather than reusing a stale identity.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "machine_id": { "type": "string" }, "agent_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "ok" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Bridge connection missing. Client must re-register via POST /api/v1/bridge/register.", "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" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/bridge/poll": { "get": { "operationId": "bridgePoll", "tags": [ "Bridge" ], "summary": "Long-poll for pending bridge tasks", "description": "Long-poll up to platform-configured `POLL_TIMEOUT_MS`. Returns 200 with tasks if any are pending, or 204 No Content on timeout (client should re-poll immediately).", "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "machine_id", "in": "query", "schema": { "type": "string" } }, { "name": "timeout", "in": "query", "schema": { "type": "integer" }, "description": "Server-side long-poll timeout override (ms)." } ], "responses": { "200": { "description": "Tasks ready for execution.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/BridgePendingTask" } } }, "required": [ "tasks" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "204": { "description": "Long-poll timeout, no tasks. Re-poll.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bridge/status": { "get": { "operationId": "bridgeStatus", "tags": [ "Bridge" ], "summary": "Get bridge connection status", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "agent_id": { "type": "string" }, "last_heartbeat": { "type": "string", "format": "date-time" }, "capabilities": { "type": "array", "items": { "type": "string" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bridge/agents": { "get": { "operationId": "listBridgeAgents", "tags": [ "Bridge" ], "summary": "List bridge agents", "responses": { "200": { "description": "Agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeConnection" } }, "total": { "type": "integer" } }, "required": [ "agents", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bridge/agents/{agentId}/capability": { "post": { "operationId": "updateBridgeAgentCapability", "tags": [ "Bridge" ], "summary": "Update agent capabilities", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "capabilities" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bridge/tasks/{taskId}/events": { "post": { "operationId": "pushBridgeTaskEvents", "tags": [ "Bridge" ], "summary": "Push task events", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "events_stored": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bridge/tasks/{taskId}/approval": { "get": { "operationId": "getBridgeTaskApproval", "tags": [ "Bridge" ], "summary": "Get approval status", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "approval_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approval", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_response": { "type": "object" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/bridge/delegate": { "post": { "operationId": "bridgeDelegate", "tags": [ "Bridge" ], "summary": "Delegate task to bridge agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "context": { "type": "object" } }, "required": [ "agent_id", "context" ] } } } }, "responses": { "200": { "description": "Delegated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "task_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/commerce/customers": { "get": { "operationId": "listCommerceCustomers", "tags": [ "Commerce" ], "summary": "List customers", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customers", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "cursor": { "type": "string" } }, "required": [ "items" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/commerce/customers/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getCommerceCustomer", "tags": [ "Commerce" ], "summary": "Get customer", "responses": { "200": { "description": "Customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateCommerceCustomer", "tags": [ "Commerce" ], "summary": "Update customer", "description": "Whitelisted fields: `name, first_name, last_name, phone, status, tags, note, addresses, accepts_marketing, verified_email, tax_exempt, currency, locale, metadata`. Unknown fields silently dropped.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteCommerceCustomer", "tags": [ "Commerce" ], "summary": "Delete customer", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/commerce/products": { "get": { "operationId": "listCommerceProducts", "tags": [ "Commerce" ], "summary": "List products", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "course", "service", "digital", "subscription" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "archived" ] } } ], "responses": { "200": { "description": "Products", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "cursor": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createCommerceProduct", "tags": [ "Commerce" ], "summary": "Create product", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "course", "service", "digital", "subscription" ] }, "price_cents": { "type": "integer" }, "currency": { "type": "string" }, "knowledge_base_ids": { "type": "array", "items": { "type": "string" } }, "agent_id": { "type": "string" }, "course_structure": { "type": "object" }, "metadata": { "type": "object" }, "slug": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "vendor": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "type": "object" } }, "compare_at_price_cents": { "type": "integer" }, "body_html": { "type": "string" }, "shopify_product_id": { "type": "string" }, "options": { "type": "array", "items": { "type": "object" } } }, "required": [ "name", "type", "price_cents", "currency" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/commerce/products/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getCommerceProduct", "tags": [ "Commerce" ], "summary": "Get product", "responses": { "200": { "description": "Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateCommerceProduct", "tags": [ "Commerce" ], "summary": "Update product", "description": "Whitelisted fields: same as create plus `stripe_price_id`. Unknown fields silently dropped.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteCommerceProduct", "tags": [ "Commerce" ], "summary": "Delete product", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/commerce/orders": { "get": { "operationId": "listCommerceOrders", "tags": [ "Commerce" ], "summary": "List orders", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "paid", "failed", "refunded" ] } } ], "responses": { "200": { "description": "Orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/commerce/orders/{id}": { "get": { "operationId": "getCommerceOrder", "tags": [ "Commerce" ], "summary": "Get order", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/commerce/enrollments": { "get": { "operationId": "listCommerceEnrollments", "tags": [ "Commerce" ], "summary": "List enrollments", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "description": "EnrollmentStatus value (active, paused, completed, cancelled, etc.)." } } ], "responses": { "200": { "description": "Enrollments", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollments": { "type": "array", "items": { "$ref": "#/components/schemas/Enrollment" } }, "total": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/commerce/enrollments/{id}": { "get": { "operationId": "getCommerceEnrollment", "tags": [ "Commerce" ], "summary": "Get enrollment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Enrollment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrollment" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/commerce/analytics": { "get": { "operationId": "getCommerceAnalytics", "tags": [ "Commerce" ], "summary": "Commerce analytics", "responses": { "200": { "description": "Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_customers": { "type": "integer" }, "total_products": { "type": "integer" }, "total_orders": { "type": "integer" }, "paid_orders": { "type": "integer" }, "total_revenue_cents": { "type": "integer" }, "active_enrollments": { "type": "integer" }, "completed_enrollments": { "type": "integer" } }, "required": [ "total_customers", "total_products", "total_orders", "total_revenue_cents" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/constitution": { "get": { "operationId": "getConstitution", "tags": [ "Governance" ], "summary": "Get constitution", "responses": { "200": { "description": "Constitution", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/ConstitutionRule" } }, "version": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "replaceConstitution", "tags": [ "Governance" ], "summary": "Replace constitution", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/ConstitutionRule" } } }, "required": [ "rules" ] } } } }, "responses": { "200": { "description": "Replaced", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/ConstitutionRule" } }, "version": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/constitution/amend": { "post": { "operationId": "amendConstitution", "tags": [ "Governance" ], "summary": "Amend constitution", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rule_id": { "type": "string" }, "action": { "type": "string" }, "rule": { "type": "object" }, "rationale": { "type": "string" } }, "required": [ "rule_id", "action" ] } } } }, "responses": { "200": { "description": "Amended", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/ConstitutionRule" } }, "version": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/ledger": { "get": { "operationId": "getGovernanceLedger", "tags": [ "Governance" ], "summary": "Get governance ledger", "parameters": [ { "name": "count", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ledger", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/GovernanceLedgerEntry" } }, "head": { "type": "string", "description": "Hash of the most recent ledger entry." }, "total": { "type": "integer" } }, "required": [ "entries", "head", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/ledger/verify": { "get": { "operationId": "verifyGovernanceLedger", "tags": [ "Governance" ], "summary": "Verify ledger integrity", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/violations/{agentId}": { "get": { "operationId": "getAgentViolations", "tags": [ "Governance" ], "summary": "Get agent violations", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Violations", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "violations": { "type": "array", "items": { "type": "object" } }, "count": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/obligations/{agentId}": { "get": { "operationId": "getAgentObligations", "tags": [ "Governance" ], "summary": "Get agent obligations", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Obligations", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/ConstitutionRule" } }, "count": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/check": { "post": { "operationId": "checkGovernance", "tags": [ "Governance" ], "summary": "Check governance compliance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "action": { "type": "string" }, "run_id": { "type": "string" }, "team_id": { "type": "string" } }, "required": [ "agent_id", "action" ] } } } }, "responses": { "200": { "description": "Check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "violations": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/voting/proposals": { "get": { "operationId": "listVotingProposals", "tags": [ "Governance" ], "summary": "List proposals", "responses": { "200": { "description": "Proposals", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposals": { "type": "array", "items": { "$ref": "#/components/schemas/VotingProposal" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createVotingProposal", "tags": [ "Governance" ], "summary": "Create proposal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "proposal_type": { "type": "string" } }, "required": [ "title", "description", "proposal_type" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/voting/proposals/{id}": { "get": { "operationId": "getVotingProposal", "tags": [ "Governance" ], "summary": "Get proposal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Proposal", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/voting/proposals/{id}/ballot": { "post": { "operationId": "castBallot", "tags": [ "Governance" ], "summary": "Cast ballot", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "maxLength": 256 }, "vote": { "type": "string" }, "weight": { "type": "number", "exclusiveMinimum": 0, "maximum": 100, "description": "Voting weight; 0 < w ≤ 100." }, "reasoning": { "type": "string" }, "signature": { "type": "string", "description": "Optional cryptographic ballot signature." } }, "required": [ "agent_id", "vote" ] } } } }, "responses": { "201": { "description": "Ballot cast", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/voting/proposals/{id}/ballots": { "get": { "operationId": "listBallots", "tags": [ "Governance" ], "summary": "List ballots", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ballots", "content": { "application/json": { "schema": { "type": "object", "properties": { "ballots": { "type": "array", "items": { "$ref": "#/components/schemas/Ballot" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/voting/proposals/{id}/tally": { "post": { "operationId": "tallyVotes", "tags": [ "Governance" ], "summary": "Tally votes", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Tally result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "outcome": { "type": "string" }, "total_votes": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/voting/proposals/{id}/veto": { "post": { "operationId": "vetoProposal", "tags": [ "Governance" ], "summary": "Veto proposal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "founder_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Vetoed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/permissions/{agentId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getAgentPermissions", "tags": [ "Governance" ], "summary": "Get agent permissions", "responses": { "200": { "description": "Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionSet" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "setAgentPermissions", "tags": [ "Governance" ], "summary": "Set agent permissions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionSet" } } } }, "responses": { "200": { "description": "Set", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/permissions/{agentId}/lineage": { "get": { "operationId": "getPermissionLineage", "tags": [ "Governance" ], "summary": "Get permission lineage", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Lineage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLineage" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/permissions/spawn-policy": { "get": { "operationId": "getSpawnPolicy", "tags": [ "Governance" ], "summary": "Get spawn policy", "responses": { "200": { "description": "Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpawnPolicy" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "setSpawnPolicy", "tags": [ "Governance" ], "summary": "Set spawn policy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpawnPolicy" } } } }, "responses": { "200": { "description": "Set", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteSpawnPolicy", "tags": [ "Governance" ], "summary": "Delete spawn policy", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/permissions/check-spawn": { "post": { "operationId": "checkSpawnPermission", "tags": [ "Governance" ], "summary": "Check spawn permission", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_agent_id": { "type": "string" }, "child_permissions": { "$ref": "#/components/schemas/PermissionSet" } }, "required": [ "parent_agent_id", "child_permissions" ] } } } }, "responses": { "200": { "description": "Check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionCheckResult" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/emergency/state": { "get": { "operationId": "getEmergencyState", "tags": [ "Governance" ], "summary": "Get emergency state", "responses": { "200": { "description": "State", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/emergency/safe-mode": { "post": { "operationId": "activateSafeMode", "tags": [ "Governance" ], "summary": "Activate safe mode", "description": "**Founder-only.** Halts all non-essential agent execution platform-wide. Admin role is NOT sufficient.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "activated_by": { "type": "string" }, "deadline_hours": { "type": "number" } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Activated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/emergency/deactivate": { "post": { "operationId": "deactivateSafeMode", "tags": [ "Governance" ], "summary": "Deactivate safe mode", "description": "**Founder-only.** Returns the platform to normal mode after a safe-mode activation.", "responses": { "200": { "description": "Deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "mode": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/emergency/root-agent": { "get": { "operationId": "getRootAgent", "tags": [ "Governance" ], "summary": "Get root agent", "responses": { "200": { "description": "Root agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "root_agent_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "setRootAgent", "tags": [ "Governance" ], "summary": "Set root agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" } }, "required": [ "agent_id" ] } } } }, "responses": { "200": { "description": "Set", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "root_agent_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/emergency/deadlock-check": { "post": { "operationId": "checkDeadlock", "tags": [ "Governance" ], "summary": "Check for deadlock", "responses": { "200": { "description": "Report", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/emergency/root-attestation": { "get": { "operationId": "getRootAttestation", "tags": [ "Governance" ], "summary": "Get root attestation", "responses": { "200": { "description": "Attestation", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "setRootAttestation", "tags": [ "Governance" ], "summary": "Set root attestation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Set", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/ambassador/ambassadors": { "get": { "operationId": "listAmbassadors", "tags": [ "Governance" ], "summary": "List ambassadors", "responses": { "200": { "description": "Ambassadors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Ambassador" } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "registerAmbassador", "tags": [ "Governance" ], "summary": "Register ambassador", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ambassador_id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "permissions": { "type": "object" } }, "required": [ "ambassador_id" ] } } } }, "responses": { "200": { "description": "Registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/ambassador/ambassadors/{id}": { "get": { "operationId": "getAmbassador", "tags": [ "Governance" ], "summary": "Get ambassador", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ambassador", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/ambassador/ambassadors/bootstrap": { "post": { "operationId": "bootstrapAmbassador", "tags": [ "Governance" ], "summary": "Bootstrap first ambassador", "responses": { "200": { "description": "Bootstrapped", "content": { "application/json": { "schema": { "type": "object", "properties": { "ambassador_id": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/ambassador/veto": { "post": { "operationId": "ambassadorVeto", "tags": [ "Governance" ], "summary": "Veto", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_type": { "type": "string" }, "target_id": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "target_type", "target_id", "reason" ] } } } }, "responses": { "200": { "description": "Vetoed", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/ambassador/vetoes": { "get": { "operationId": "listAmbassadorVetoes", "tags": [ "Governance" ], "summary": "List vetoes", "responses": { "200": { "description": "Vetoes", "content": { "application/json": { "schema": { "type": "object", "properties": { "vetoes": { "type": "array", "items": { "$ref": "#/components/schemas/Veto" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/ambassador/requests": { "post": { "operationId": "createAmbassadorRequest", "tags": [ "Governance" ], "summary": "Create request", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_agent_id": { "type": "string" }, "type": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" } }, "required": [ "from_agent_id", "type", "subject", "body" ] } } } }, "responses": { "200": { "description": "Request created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "get": { "operationId": "listAmbassadorRequests", "tags": [ "Governance" ], "summary": "List requests", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "acknowledged", "resolved" ] } } ], "responses": { "200": { "description": "Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/AmbassadorRequest" } } }, "required": [ "requests" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/ambassador/requests/{id}/resolve": { "post": { "operationId": "resolveAmbassadorRequest", "tags": [ "Governance" ], "summary": "Resolve request", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" } }, "required": [ "response" ] } } } }, "responses": { "200": { "description": "Resolved", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/arbiter/registry": { "get": { "operationId": "getArbiterRegistry", "tags": [ "Governance" ], "summary": "Get arbiter registry", "responses": { "200": { "description": "Registry", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "setArbiterRegistry", "tags": [ "Governance" ], "summary": "Set arbiter registry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Set", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/arbiter/cases": { "get": { "operationId": "listArbiterCases", "tags": [ "Governance" ], "summary": "List cases", "responses": { "200": { "description": "Cases", "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "array", "items": { "$ref": "#/components/schemas/ArbiterCase" } } }, "required": [ "cases" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "fileArbiterCase", "tags": [ "Governance" ], "summary": "File case", "description": "Files a new arbitration case. Returns 409 if the filer would have a conflict of interest with the chosen arbiter pool (server checks before persisting).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filed_by": { "type": "string" }, "against_agent_id": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "filed_by", "against_agent_id" ] } } } }, "responses": { "201": { "description": "Filed", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/arbiter/cases/{id}": { "get": { "operationId": "getArbiterCase", "tags": [ "Governance" ], "summary": "Get case", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Case", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/arbiter/cases/{id}/ruling": { "post": { "operationId": "issueArbiterRuling", "tags": [ "Governance" ], "summary": "Issue ruling", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string" }, "penalties": { "type": "array", "items": { "type": "object" } } }, "required": [ "decision" ] } } } }, "responses": { "200": { "description": "Ruling issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/arbiter/cases/{id}/appeal": { "post": { "operationId": "fileArbiterAppeal", "tags": [ "Governance" ], "summary": "File appeal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filed_by": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "filed_by", "reason" ] } } } }, "responses": { "200": { "description": "Appeal filed", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/builder/requests": { "get": { "operationId": "listBuilderRequests", "tags": [ "Governance" ], "summary": "List design requests", "responses": { "200": { "description": "Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/DesignRequest" } } }, "required": [ "requests" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createBuilderRequest", "tags": [ "Governance" ], "summary": "Create design request", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignRequest" } } } }, "responses": { "201": { "description": "Request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignRequest" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/builder/requests/{id}": { "get": { "operationId": "getBuilderRequest", "tags": [ "Governance" ], "summary": "Get design request", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignRequest" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/builder/requests/{id}/status": { "put": { "operationId": "updateBuilderRequestStatus", "tags": [ "Governance" ], "summary": "Update request status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "voting", "approved", "rejected", "spawned" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignRequest" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/improvement/{agentId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listImprovementProposals", "tags": [ "Governance" ], "summary": "List improvement proposals", "responses": { "200": { "description": "Proposals", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ImprovementProposal" } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createImprovementProposal", "tags": [ "Governance" ], "summary": "Create improvement proposal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ] } } } }, "responses": { "200": { "description": "Proposal created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/improvement/{agentId}/{version}": { "get": { "operationId": "getImprovementProposal", "tags": [ "Governance" ], "summary": "Get proposal", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Proposal", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/improvement/{agentId}/{version}/status": { "put": { "operationId": "updateImprovementStatus", "tags": [ "Governance" ], "summary": "Update proposal status (state machine enforced)", "description": "Allowed transitions:\n- `proposed` → `arbiter_review` | `rejected`\n- `arbiter_review` → `voting` | `rejected`\n- `voting` → `sandbox_testing` | `rejected`\n- `sandbox_testing` → `approved` | `rejected`\n- `approved` → `applied`\n\nAny other transition returns 400. Requires admin/founder role.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "proposed", "arbiter_review", "voting", "sandbox_testing", "approved", "applied", "rejected" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/goals": { "get": { "operationId": "listGoals", "tags": [ "Governance" ], "summary": "List goals", "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Goals", "content": { "application/json": { "schema": { "type": "object", "properties": { "goals": { "type": "array", "items": { "$ref": "#/components/schemas/Goal" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createGoal", "tags": [ "Governance" ], "summary": "Create goal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" } }, "required": [ "agent_id" ] } } } }, "responses": { "200": { "description": "Goal created", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/governance/goals/{id}": { "get": { "operationId": "getGoal", "tags": [ "Governance" ], "summary": "Get goal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Goal", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/governance/goals/{id}/status": { "put": { "operationId": "updateGoalStatus", "tags": [ "Governance" ], "summary": "Update goal status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/marketplace/invocations/{invocationId}": { "get": { "operationId": "getMarketplaceInvocation", "tags": [ "Marketplace" ], "summary": "Get invocation status", "parameters": [ { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invocation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceInvocation" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "marketplace:read" ] } ] } }, "/api/v1/registry/publish": { "post": { "operationId": "registryPublish", "summary": "Publish a new spec version to the registry", "description": "Multipart upload of a tarball + manifest. Server validates manifest, verifies optional sha256, and persists the artifact. Returns the full PublishedSpec record. `Location` header points at the version's metadata endpoint.", "tags": [ "Registry" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "manifest": { "type": "string", "description": "JSON-stringified SpecManifest, validated server-side." }, "artifact": { "type": "string", "format": "binary", "description": "Spec bundle (.tar.zst). Size capped per platform config." }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hex sha256; verified if provided." }, "attestation": { "type": "string", "description": "Optional JSON-stringified SLSA attestation." } }, "required": [ "manifest", "artifact" ] } } } }, "responses": { "201": { "description": "Spec version published", "headers": { "Location": { "schema": { "type": "string" }, "description": "URL of the new spec version metadata." }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "publisher_tenant_id": { "type": "string" }, "manifest": { "type": "object" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer" }, "artifact_key": { "type": "string" }, "dependencies": { "type": "array", "items": { "type": "object" } }, "yanked": { "type": "boolean" }, "yanked_reason": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "shared_with": { "type": "array", "items": { "type": "string" } }, "attestation": { "type": "object" }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "scope", "name", "version", "publisher_tenant_id", "manifest", "sha256", "size_bytes", "visibility", "published_at" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/registry/search": { "get": { "operationId": "registrySearch", "summary": "Search the registry for specs", "tags": [ "Registry" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "keyword", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "publisher_tenant_id": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "next_cursor": { "type": "string" } }, "required": [ "hits", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/registry/admin/specs": { "get": { "operationId": "registryAdminListSpecs", "summary": "Admin: list all specs (regardless of visibility)", "tags": [ "Registry" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "All specs", "content": { "application/json": { "schema": { "type": "object", "properties": { "specs": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" }, "owner_tenant_id": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "latest_version": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "size_bytes": { "type": "integer" }, "yanked": { "type": "boolean" }, "shared_with_count": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" } } } }, "next_cursor": { "type": "string" } }, "required": [ "specs" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/registry/index/{shard}/{scope}/{name}": { "parameters": [ { "name": "shard", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "registryGetSparseIndex", "summary": "Get sparse-index entry for a spec", "tags": [ "Registry" ], "responses": { "200": { "description": "Sparse index — version listing optimised for resolver clients.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "sha256": { "type": "string" }, "dependencies": { "type": "array", "items": { "type": "object" } }, "yanked": { "type": "boolean" }, "yank_reason": { "type": "string" }, "size": { "type": "integer" }, "published_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "scope", "name", "versions" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/registry/spec/{scope}/{name}": { "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "registryGetSpecMetadata", "summary": "Get spec metadata (latest version pointers, owners)", "tags": [ "Registry" ], "responses": { "200": { "description": "Spec metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "license": { "type": "string" }, "repository": { "type": "string" }, "homepage": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "shared_with": { "type": "array", "items": { "type": "string" } }, "owner_tenant_id": { "type": "string" }, "latest_version": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "tool_count": { "type": "integer" }, "skill_count": { "type": "integer" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "schema_version": { "type": "string" } }, "required": [ "scope", "name", "visibility", "owner_tenant_id", "latest_version" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/registry/spec/{scope}/{name}/share": { "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "registryGetShare", "summary": "Get share/visibility settings for a spec", "tags": [ "Registry" ], "responses": { "200": { "description": "Share settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" }, "shared_with": { "type": "array", "items": { "type": "string" } }, "owner_tenant_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "scope", "name", "shared_with", "owner_tenant_id", "updated_at" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "registrySetShare", "summary": "Set share/visibility settings for a spec", "tags": [ "Registry" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_with": { "type": "array", "items": { "type": "string" }, "description": "Tenant IDs allowed to read this private spec." } }, "required": [ "shared_with" ] } } } }, "responses": { "200": { "description": "Share settings updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" }, "shared_with": { "type": "array", "items": { "type": "string" } }, "owner_tenant_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/registry/spec/{scope}/{name}/{version}": { "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "registryGetSpecVersion", "summary": "Get a specific version of a spec", "description": "Returns the full PublishedSpec record plus a `download_url` pointing at the artifact endpoint.", "tags": [ "Registry" ], "responses": { "200": { "description": "Spec version", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "manifest": { "type": "object" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer" }, "dependencies": { "type": "array", "items": { "type": "object" } }, "yanked": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "shared_with": { "type": "array", "items": { "type": "string" } }, "published_at": { "type": "string", "format": "date-time" }, "download_url": { "type": "string", "format": "uri" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/registry/spec/{scope}/{name}/{version}/artifact": { "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "registryGetArtifact", "summary": "Download tarball/artifact bundle for a spec version", "tags": [ "Registry" ], "responses": { "200": { "description": "Zstandard-compressed tar artifact bytes.", "headers": { "Content-Length": { "schema": { "type": "integer" } }, "X-Content-Sha256": { "schema": { "type": "string" } }, "X-Artifact-SHA256": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "public, max-age=31536000, immutable" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/zstd": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/registry/spec/{scope}/{name}/{version}/readme": { "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "registryGetReadme", "summary": "Get README for a spec version", "tags": [ "Registry" ], "responses": { "200": { "description": "README text (empty string when artifact has no README).", "content": { "application/json": { "schema": { "type": "object", "properties": { "readme": { "type": "string" } }, "required": [ "readme" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/registry/spec/{scope}/{name}/{version}/files": { "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "registryListFiles", "summary": "List files inside a spec version artifact", "tags": [ "Registry" ], "responses": { "200": { "description": "File list", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer" }, "binary": { "type": "boolean" } } } } }, "required": [ "files" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/registry/spec/{scope}/{name}/{version}/file": { "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 1024 }, "description": "Relative path within the artifact." } ], "get": { "operationId": "registryGetFile", "summary": "Get a single file from inside a spec version artifact", "tags": [ "Registry" ], "responses": { "200": { "description": "File content metadata + base64/string body when text.", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer" }, "binary": { "type": "boolean" }, "truncated": { "type": "boolean" }, "content": { "type": [ "string", "null" ], "description": "UTF-8 text body. `null` when `binary: true`." } }, "required": [ "path", "size", "binary", "truncated" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/registry/spec/{scope}/{name}/{version}/yank": { "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "registryYankVersion", "summary": "Yank (mark unsafe) a published spec version", "tags": [ "Registry" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "204": { "description": "Version yanked", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/registry/spec/{scope}/{name}/{version}/unyank": { "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "registryUnyankVersion", "summary": "Reverse a yank on a published spec version", "tags": [ "Registry" ], "responses": { "204": { "description": "Version unyanked", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/webhooks/dlq": { "get": { "operationId": "adminListWebhookDlq", "summary": "List dead-lettered webhook deliveries", "tags": [ "Admin" ], "responses": { "200": { "description": "DLQ entries (sorted DESC by timestamp).", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string" }, "payload": { "type": "object" }, "errorMessage": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "tenantId": { "type": [ "string", "null" ] } }, "required": [ "eventId", "eventType", "errorMessage", "timestamp" ] } } }, "required": [ "entries" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/webhooks/dlq/{eventId}/replay": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "adminReplayWebhookDlq", "summary": "Replay a dead-lettered webhook event", "tags": [ "Admin" ], "responses": { "200": { "description": "Replayed (handler ran successfully).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "eventId": { "type": "string" }, "action": { "type": "string" }, "message": { "type": "string" } }, "required": [ "success", "eventId", "action", "message" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "description": "Billing not configured for this deployment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/data-explorer/raw-keys": { "get": { "operationId": "adminDataExplorerRawKeys", "summary": "Full KV scan (admin diagnostic)", "description": "Dangerous: full DB key scan. Admin-only. Use the namespace-scoped endpoints under `/admin/data-explorer/*` for normal browsing.", "tags": [ "Admin" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } }, { "name": "prefix", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated KV key parts; restricts the scan range." }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw key listing", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } }, "namespace": { "type": "string" }, "value_preview": { "type": "string" }, "size": { "type": "integer" }, "type": { "type": "string", "enum": [ "null", "array", "string", "number", "boolean", "object", "undefined" ] }, "sensitive": { "type": "boolean" } } } }, "cursor": { "type": "string" }, "total": { "type": "integer" } }, "required": [ "keys", "total" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "501": { "description": "Backend `kvListRaw` not available in this deployment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/reconciliation/{tenantId}": { "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "adminGetReconciliation", "summary": "Get last stored cost-reconciliation result for a tenant", "tags": [ "Admin" ], "responses": { "200": { "description": "Reconciliation report", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "reconciliation": { "type": "object", "additionalProperties": true, "properties": { "period": { "type": "string" } } } }, "required": [ "tenant_id", "reconciliation" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/analytics/overview": { "get": { "operationId": "adminAnalyticsOverview", "summary": "Platform-wide analytics overview", "tags": [ "Admin" ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 90, "minimum": 1 } } ], "responses": { "200": { "description": "Overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "days": { "type": "integer" } } }, "totals": { "type": "object", "properties": { "landing_visit": { "type": "integer" }, "page_view": { "type": "integer" }, "signup": { "type": "integer" }, "login": { "type": "integer" }, "app_open": { "type": "integer" } } }, "unique_visitors_30d": { "type": "integer" }, "signups_30d": { "type": "integer" }, "conversion_rate": { "type": "number" }, "timeseries": { "type": "array", "items": { "type": "object" } }, "top_countries": { "type": "array", "items": { "type": "object" } }, "top_devices": { "type": "array", "items": { "type": "object" } }, "top_browsers": { "type": "array", "items": { "type": "object" } }, "top_referrers": { "type": "array", "items": { "type": "object" } }, "top_utm_sources": { "type": "array", "items": { "type": "object" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/analytics/events": { "get": { "operationId": "adminAnalyticsEvents", "summary": "Platform-wide event analytics", "tags": [ "Admin" ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 7, "maximum": 30, "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } }, { "name": "type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Events analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string" }, "ts": { "type": "string", "format": "date-time" }, "type": { "type": "string" }, "visitor_id": { "type": "string" }, "tenant_id": { "type": "string" }, "country": { "type": "string" }, "device_type": { "type": "string", "enum": [ "mobile", "tablet", "desktop", "bot", "unknown" ] }, "browser": { "type": "string" }, "os": { "type": "string" }, "language": { "type": "string" }, "referrer_host": { "type": "string" }, "path": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_campaign": { "type": "string" }, "ip_hash": { "type": "string" } } } }, "count": { "type": "integer" } }, "required": [ "items", "count" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/analytics/agents": { "get": { "operationId": "adminAnalyticsAgents", "summary": "Platform-wide agent analytics", "tags": [ "Admin" ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 90, "minimum": 1 } } ], "responses": { "200": { "description": "Agent analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAnalyticsSummary" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/analytics/agents": { "get": { "operationId": "tenantAnalyticsAgents", "summary": "Tenant-scoped agent analytics", "tags": [ "Analytics" ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 90, "minimum": 1 } } ], "responses": { "200": { "description": "Per-tenant agent analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAnalyticsSummary" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "read:analytics" ] } ] } }, "/api/v1/admin/tools": { "get": { "operationId": "adminListTools", "summary": "Admin: enumerate available built-in tools", "tags": [ "Admin" ], "responses": { "200": { "description": "Tool inventory", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "JSON Schema for tool parameters." } } } }, "count": { "type": "integer" } }, "required": [ "tools", "count" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/config/landing": { "get": { "operationId": "adminGetLandingConfig", "summary": "Admin: get landing-page featured-agent config", "tags": [ "Admin" ], "responses": { "200": { "description": "Landing config", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "adminPutLandingConfig", "summary": "Admin: set landing-page featured-agent config", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/model-pricing": { "get": { "operationId": "adminGetModelPricing", "summary": "Admin: live per-model pricing (synced from Together AI)", "tags": [ "Admin" ], "responses": { "200": { "description": "Pricing snapshot", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/config/model-catalog": { "get": { "operationId": "adminGetModelCatalog", "summary": "Admin: get curated model catalog", "tags": [ "Admin" ], "responses": { "200": { "description": "Model catalog", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "adminPutModelCatalog", "summary": "Admin: replace curated model catalog", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/model-catalog/seed": { "get": { "operationId": "adminGetModelCatalogSeed", "summary": "Admin: model catalog default seed", "tags": [ "Admin" ], "responses": { "200": { "description": "Seed catalog", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] } }, "/api/v1/admin/config/voice-presets": { "get": { "operationId": "adminGetVoicePresets", "summary": "Admin: get per-model voice presets", "tags": [ "Admin" ], "responses": { "200": { "description": "Voice presets", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "adminPutVoicePresets", "summary": "Admin: set per-model voice presets", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/voice": { "get": { "operationId": "adminGetVoiceConfig", "summary": "Admin: get default voice (STT/TTS) config", "tags": [ "Admin" ], "responses": { "200": { "description": "Voice config", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "adminPutVoiceConfig", "summary": "Admin: set default voice config", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/image-generation": { "get": { "operationId": "adminGetImageGenerationConfig", "summary": "Admin: get default image-generation config", "tags": [ "Admin" ], "responses": { "200": { "description": "Image-generation config", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "adminPutImageGenerationConfig", "summary": "Admin: set default image-generation config", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/image-edit": { "get": { "operationId": "adminGetImageEditConfig", "summary": "Admin: get default image-edit (img2img) config", "tags": [ "Admin" ], "responses": { "200": { "description": "Image-edit config", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "adminPutImageEditConfig", "summary": "Admin: set default image-edit config", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/admin/config/video-generation": { "get": { "operationId": "adminGetVideoGenerationConfig", "summary": "Admin: get default video-generation config", "tags": [ "Admin" ], "responses": { "200": { "description": "Video-generation config", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ] }, "put": { "operationId": "adminPutVideoGenerationConfig", "summary": "Admin: set default video-generation config", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } } }, "tags": [ { "name": "Registry", "description": "Spec registry — publish, search, yank, share spec artifacts" }, { "name": "Admin", "description": "Platform admin: tenants, audit, reconciliation, DLQ, analytics" }, { "name": "Analytics", "description": "Tenant-scoped usage analytics" }, { "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": "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" }, { "name": "Governance", "description": "Agent governance: constitution, voting, permissions, emergency protocols" }, { "name": "Bridge", "description": "Local agent bridge for Snaga desktop connections" }, { "name": "Commerce", "description": "E-commerce: products, customers, orders, enrollments" }, { "name": "Feed", "description": "Activity feed and real-time event streaming" }, { "name": "Users", "description": "User management, invites, roles" }, { "name": "Admin Config", "description": "Platform configuration: pricing, plans, feature flags, rate limits, runtime" }, { "name": "Data Explorer", "description": "KV data explorer for admin diagnostics" }, { "name": "Public", "description": "Unauthenticated public-facing endpoints" } ] }