{ "openapi": "3.1.0", "info": { "title": "Atako API", "version": "0.1.0", "description": "The Atako customer API — manage AI agents, their files, integrations, billing, and your company/team, programmatically.\n\n## Authentication\n\nEvery non-public endpoint takes a Bearer token that is either:\n- a **programmatic API key** (`aik_…`) — create one at [app.atako.ai](https://app.atako.ai) → Settings → API keys (company-admin only), or\n- a **Supabase session JWT** — what the web app itself sends; not practical to obtain outside a browser session.\n\n```bash\ncurl https://api.atako.ai/agents -H \"Authorization: Bearer aik_...\"\n```\n\nAn API key acts as its owning user, with all of that user's permissions — there is no separate key scope in this release.\n\n## Other Atako HTTP surfaces (not covered by this spec)\n\n- **Atako MCP server** — `POST /mcp` (auth: same Bearer token as above) exposes a read-only Model Context Protocol tool catalogue for AI clients (Claude Code, Claude Desktop, Cursor, ChatGPT). See [docs.atako.ai/developers/mcp/overview](https://docs.atako.ai/developers/mcp/overview).\n- **Content API** (`cak_…` key, `/content/*`) — a separate, more restricted key type for headless CMS-style access to blog/news/use-case content. Not documented here.\n\n## Errors\n\nErrors use a JSON envelope: `{ \"error\": string, \"code\"?: string }`. `error` is either a short human-readable message or a SCREAMING_SNAKE_CASE code, depending on the route — treat it as an opaque string to match against, not a stable enum across the whole API.\n\n## Rate limits\n\nAuthenticated routes: 6000 requests/min per user (`authRateLimit`). Public GET routes: 60/min per IP. A handful of sensitive public POST routes (newsletter signup, email-exists, invitation preview) are limited to 10 requests / 15 min per IP.\n\n## Pagination\n\nList endpoints use either simple `limit`/`offset` query params (marketing content — a plain JSON array response, capped at the documented max) or `page`/`limit` (credit transactions). Neither returns a total count today; fetch until a page comes back shorter than `limit`." }, "servers": [ { "url": "https://api.atako.ai", "description": "Production" } ], "tags": [ { "name": "Agents" }, { "name": "Messages" }, { "name": "Activity" }, { "name": "Agent Options" }, { "name": "API Keys" }, { "name": "Files" }, { "name": "Cron Jobs" }, { "name": "Sub-Agents" }, { "name": "Interagent Messages" }, { "name": "Integrations" }, { "name": "Subscriptions" }, { "name": "Users" }, { "name": "Company" }, { "name": "Teams" }, { "name": "Public" }, { "name": "Marketing Content" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An `aik_…` programmatic API key (app.atako.ai → Settings → API keys) or a Supabase session JWT." } }, "schemas": { "Error": { "type": "object", "description": "Atako's standard error envelope. `error` is either a short human-readable message or a SCREAMING_SNAKE_CASE code (routes are inconsistent about which — treat it as an opaque string and match on it exactly if you need to branch on error type). Some routes add extra fields alongside `error` (see the operation's own error responses).", "properties": { "error": { "type": "string" }, "code": { "type": "string", "description": "Present on some routes; a stable machine-readable code duplicating or refining `error`." } }, "required": [ "error" ], "additionalProperties": true }, "LocalizedText": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "LocalizedStringArray": { "type": "object", "description": "Same shape as LocalizedText, but each locale holds a string array.", "properties": { "fr": { "type": "array", "items": { "type": "string" } } }, "required": [ "fr" ], "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "AgentStatus": { "type": "string", "enum": [ "active", "completed", "paused", "provisioning", "unresponsive", "failed" ] }, "ActivitySummary": { "type": "object", "nullable": true, "description": "In-memory working/idle snapshot for the agent, or null when nothing is tracked yet.", "properties": { "working": { "type": "boolean" }, "labelKey": { "type": "string" }, "labelParams": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "working" ] }, "Agent": { "type": "object", "description": "List-view agent summary, as returned by GET /agents.", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "type": "string", "format": "uuid" }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "teamName": { "type": "string", "nullable": true }, "scope": { "type": "string", "enum": [ "personal", "team" ] }, "access": { "type": "string", "enum": [ "owner", "team" ] }, "ownerName": { "type": "string" }, "status": { "$ref": "#/components/schemas/AgentStatus" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "name": { "type": "string" }, "image": { "type": "string", "description": "PNG filename under apps/web/public/aiygents/." }, "engine": { "type": "string", "enum": [ "openclaw", "hermes" ] }, "lastMessage": { "type": "object", "nullable": true, "description": "List-view preview only — content truncated to 280 chars server-side.", "properties": { "role": { "type": "string" }, "content": { "type": "string", "maxLength": 280 }, "timestamp": { "type": "string", "format": "date-time" } } }, "hasUnreadMessages": { "type": "boolean" }, "activity": { "$ref": "#/components/schemas/ActivitySummary" } }, "required": [ "id", "clientId", "scope", "access", "status", "name", "image", "engine", "hasUnreadMessages" ] }, "AgentDetail": { "type": "object", "description": "Single-agent detail, as returned by GET /agents/{id}.", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "type": "string", "format": "uuid" }, "clientName": { "type": "string" }, "clientCompany": { "type": "string", "nullable": true }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "teamName": { "type": "string", "nullable": true }, "scope": { "type": "string", "enum": [ "personal", "team" ] }, "access": { "type": "string", "enum": [ "owner", "team" ] }, "status": { "$ref": "#/components/schemas/AgentStatus" }, "startDate": { "type": "string", "format": "date-time" }, "activatedAt": { "type": "string", "format": "date-time", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "lastHeartbeatAt": { "type": "string", "format": "date-time", "nullable": true }, "upgradingAt": { "type": "string", "format": "date-time", "nullable": true }, "name": { "type": "string" }, "image": { "type": "string" }, "directModelId": { "type": "string", "nullable": true, "description": "Raw model id for a direct-provider (BYOK openai/anthropic) agent; null for an OpenRouter-catalogue agent." }, "engine": { "type": "string", "enum": [ "openclaw", "hermes" ] }, "engineVersion": { "type": "string", "nullable": true }, "engineRequestedVersion": { "type": "string", "nullable": true }, "machineLost": { "type": "boolean" }, "activity": { "$ref": "#/components/schemas/ActivitySummary" } }, "required": [ "id", "clientId", "scope", "access", "status", "name", "image", "engine", "machineLost" ] }, "AgentRecord": { "type": "object", "description": "The raw `agents` table row, returned verbatim by POST /agents (201) and POST /agents/{id}/end (200, under `.session`). Every column, including several operational/internal fields not otherwise exposed.", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "type": "string", "format": "uuid" }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "image": { "type": "string" }, "systemPrompt": { "type": "string", "nullable": true }, "modelId": { "type": "string", "format": "uuid", "nullable": true }, "directModelId": { "type": "string", "nullable": true }, "modelConfig": { "type": "object", "nullable": true, "description": "Per-task-type model overrides.", "properties": { "vision": { "type": "string", "nullable": true }, "low_effort": { "type": "string", "nullable": true }, "medium_effort": { "type": "string", "nullable": true }, "high_effort": { "type": "string", "nullable": true } } }, "llmKeyId": { "type": "string", "format": "uuid", "nullable": true, "description": "Set for a BYOK agent (company LLM provider key); null for the platform key." }, "harnessId": { "type": "string", "format": "uuid", "nullable": true }, "engine": { "type": "string", "enum": [ "openclaw", "hermes" ] }, "status": { "$ref": "#/components/schemas/AgentStatus" }, "agentAuthTokenHash": { "type": "string", "nullable": true }, "agentAuthIssuedAt": { "type": "string", "format": "date-time", "nullable": true }, "agentAuthLastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "startDate": { "type": "string", "format": "date-time" }, "activatedAt": { "type": "string", "format": "date-time", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "lastHeartbeatAt": { "type": "string", "format": "date-time", "nullable": true }, "lastReadAt": { "type": "string", "format": "date-time", "nullable": true }, "engineVersion": { "type": "string", "nullable": true }, "engineImage": { "type": "string", "nullable": true }, "engineRequestedVersion": { "type": "string", "nullable": true }, "upgradingAt": { "type": "string", "format": "date-time", "nullable": true }, "upgradeRequestedAt": { "type": "string", "format": "date-time", "nullable": true }, "upgradeStatus": { "type": "string", "enum": [ "requested", "running", "succeeded", "failed" ], "nullable": true }, "upgradeError": { "type": "string", "nullable": true }, "provisioningError": { "type": "string", "nullable": true }, "pausedAt": { "type": "string", "format": "date-time", "nullable": true }, "pausedReason": { "type": "string", "nullable": true }, "clientContext": { "type": "string", "nullable": true, "description": "Per-agent \"contexte business\" free text." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientId", "name", "image", "engine", "status", "startDate", "createdAt" ] }, "CreateAgentBody": { "type": "object", "required": [ "name", "image" ], "properties": { "name": { "type": "string", "minLength": 1 }, "image": { "type": "string", "description": "PNG filename under apps/web/public/aiygents/." }, "systemPrompt": { "type": "string", "nullable": true, "description": "Free-text agent instructions, trimmed." }, "clientContext": { "type": "string", "description": "Free-text per-agent business context, trimmed." }, "modelId": { "type": "string", "format": "uuid", "description": "From GET /models. Omitted → admin-declared default model." }, "harnessId": { "type": "string", "format": "uuid", "description": "From GET /harnesses." }, "teamId": { "type": "string", "format": "uuid", "nullable": true, "description": "Assigns the agent to a shared team instead of keeping it personal." }, "modelConfig": { "type": "object", "description": "Per-task-type model overrides, forwarded to the orchestrator webhook.", "properties": { "vision": { "type": "string", "nullable": true }, "low_effort": { "type": "string", "nullable": true }, "medium_effort": { "type": "string", "nullable": true }, "high_effort": { "type": "string", "nullable": true } } }, "engine": { "type": "string", "enum": [ "openclaw", "hermes" ], "description": "Defaults to openclaw." }, "llmKeyId": { "type": "string", "format": "uuid", "description": "BYOK: id of a company LLM provider key (see docs — BYOK key management is not part of this customer API cut)." } } }, "UpgradeStatus": { "type": "object", "properties": { "available": { "type": "boolean", "description": "True only when `target` is strictly semver-newer than `current`." }, "current": { "type": "string", "nullable": true }, "target": { "type": "string", "nullable": true }, "upgrading": { "type": "boolean" }, "upgradeStatus": { "type": "string", "enum": [ "requested", "running", "succeeded", "failed" ], "nullable": true }, "upgradeError": { "type": "string", "nullable": true } }, "required": [ "available", "upgrading" ] }, "AiModel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "modelId": { "type": "string", "description": "OpenRouter-style model id, e.g. \"openai/gpt-4-turbo\"." }, "name": { "type": "string" }, "logoUrl": { "type": "string", "nullable": true }, "termsUrl": { "type": "string", "nullable": true }, "visible": { "type": "boolean" }, "taskTypes": { "type": "array", "items": { "type": "string" } }, "promptPrice": { "type": "string", "nullable": true }, "completionPrice": { "type": "string", "nullable": true }, "contextLength": { "type": "integer", "nullable": true }, "isFree": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "recommendedFor": { "type": "array", "items": { "type": "string" }, "description": "Task types this model is the admin-curated recommendation for (e.g. 'vision', 'low_effort')." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "modelId", "name", "visible" ] }, "Harness": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "logoUrl": { "type": "string", "nullable": true }, "termsUrl": { "type": "string", "nullable": true }, "visible": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "visible" ] }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "agent" ] }, "content": { "type": "string" }, "meta": { "type": "object", "additionalProperties": true }, "flaggedAsError": { "type": "boolean" }, "deliveryState": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "role", "content", "timestamp" ] }, "ActivityEvent": { "type": "object", "description": "One entry of the live-activity feed (GET /agents/{agentId}/activity).", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "eventId": { "type": "string" }, "seq": { "type": "number" }, "ts": { "type": "string", "format": "date-time" }, "origin": { "type": "object", "description": "Discriminated on `kind`: 'chat' | 'cron' | 'subagent' | 'system' | 'email' | 'webhook' | 'interagent', each with kind-specific extra fields (conversationKey, cronJobId, subAgentId, threadId, endpointId, contextId, …).", "properties": { "kind": { "type": "string", "enum": [ "chat", "cron", "subagent", "system", "email", "webhook", "interagent" ] } }, "required": [ "kind" ], "additionalProperties": true }, "turnId": { "type": "string" }, "type": { "type": "string", "enum": [ "turn.started", "turn.finished", "thinking.step", "tool.started", "tool.finished", "plan.updated", "subagent.started", "subagent.finished", "integration.call", "llm_call" ] }, "category": { "type": "string", "enum": [ "web", "files", "memory", "code", "integration", "planning", "delegation", "llm", "other" ] }, "labelKey": { "type": "string" }, "labelParams": { "type": "object", "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "running", "ok", "error" ] }, "durationMs": { "type": "number" }, "detail": { "type": "object", "description": "Event-type-specific extra data (tool name/args/result previews, token counts, todos, integration call info, error message, …).", "additionalProperties": true } }, "required": [ "id", "agentId", "eventId", "seq", "ts", "type", "labelKey" ] }, "ActivityState": { "type": "object", "properties": { "working": { "type": "boolean" }, "labelKey": { "type": "string" }, "labelParams": { "type": "object", "additionalProperties": { "type": "string" } }, "since": { "type": "string", "format": "date-time" }, "lastPlan": { "type": "object", "properties": { "todos": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string" }, "status": { "type": "string" } } } }, "ts": { "type": "string", "format": "date-time" } } } }, "required": [ "working", "since" ] }, "FileNode": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "type": "string", "format": "uuid" }, "parentId": { "type": "string", "format": "uuid", "nullable": true }, "type": { "type": "string", "enum": [ "folder", "file" ] }, "name": { "type": "string" }, "storagePath": { "type": "string", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "fileSize": { "type": "integer", "nullable": true }, "agentTag": { "type": "string", "format": "uuid", "nullable": true }, "uploadSource": { "type": "string", "enum": [ "client", "agent" ], "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientId", "type", "name", "createdAt" ] }, "SignedDownloadUrl": { "type": "object", "properties": { "signedUrl": { "type": "string", "format": "uri" }, "expiresIn": { "type": "integer", "description": "Seconds; 3600." } }, "required": [ "signedUrl", "expiresIn" ] }, "SignedUploadUrl": { "type": "object", "properties": { "signedUrl": { "type": "string", "format": "uri" }, "storagePath": { "type": "string" }, "token": { "type": "string" } }, "required": [ "signedUrl", "storagePath", "token" ] }, "FileGrant": { "type": "object", "description": "A client file/folder granted to an agent (GET/POST /agents/{agentId}/file-grants).", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "nodeId": { "type": "string", "format": "uuid" }, "grantedBy": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "node": { "type": "object", "description": "Only present on the list endpoint (joined).", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "folder", "file" ] }, "storagePath": { "type": "string", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "fileSize": { "type": "integer", "nullable": true }, "parentId": { "type": "string", "format": "uuid", "nullable": true }, "agentTag": { "type": "string", "format": "uuid", "nullable": true }, "uploadSource": { "type": "string", "enum": [ "client", "agent" ], "nullable": true } } } }, "required": [ "id", "agentId", "nodeId", "createdAt" ] }, "DedicatedFolderResult": { "type": "object", "properties": { "folder": { "$ref": "#/components/schemas/FileNode" }, "grant": { "allOf": [ { "$ref": "#/components/schemas/FileGrant" } ], "nullable": true }, "existing": { "type": "boolean" } }, "required": [ "folder", "existing" ] }, "CronExecution": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "cronJobId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "running", "success", "failed" ] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "durationMs": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true }, "output": { "type": "string", "nullable": true, "description": "Execution content (F1.1, agent-cron-channel)." }, "summary": { "type": "string", "nullable": true }, "businessState": { "type": "string", "enum": [ "ok", "failed" ], "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "cronJobId", "state", "startedAt" ] }, "CronJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "prompt": { "type": "string" }, "schedule": { "type": "string", "description": "Cron expression (or a deterministic \"once at \" one-shot)." }, "nextRunAt": { "type": "string", "format": "date-time", "nullable": true }, "lastRunAt": { "type": "string", "format": "date-time", "nullable": true }, "lastRunState": { "type": "string", "enum": [ "running", "success", "failed" ], "nullable": true }, "enabled": { "type": "boolean" }, "timezone": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "executions": { "type": "array", "description": "Up to 20 most recent executions.", "items": { "$ref": "#/components/schemas/CronExecution" } } }, "required": [ "id", "agentId", "title", "prompt", "schedule", "enabled", "createdAt" ] }, "CronJobsResponse": { "type": "object", "properties": { "channelEnabled": { "type": "boolean", "description": "AGENT_CRON_CHANNEL_ENABLED." }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/CronJob" } } }, "required": [ "channelEnabled", "jobs" ] }, "SubAgent": { "type": "object", "description": "Deduplicated by name (case-insensitive) — most recent run per logical sub-agent.", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "engineId": { "type": "string" }, "name": { "type": "string" }, "model": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "timed_out", "cancelled" ] }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "engineId", "name", "status" ] }, "InteragentMessageListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "sent", "received" ] }, "peerAgentId": { "type": "string", "format": "uuid" }, "peerAgentName": { "type": "string" }, "peerAgentImage": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "bodyPreview": { "type": "string", "maxLength": 300 }, "deliveryState": { "type": "string", "enum": [ "pending_agent", "delivered" ] }, "contextId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "hopCount": { "type": "integer" }, "replyToId": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "direction", "peerAgentId", "deliveryState", "contextId", "createdAt" ] }, "InteragentMessageDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fromAgentId": { "type": "string", "format": "uuid" }, "fromAgentName": { "type": "string" }, "toAgentId": { "type": "string", "format": "uuid" }, "toAgentName": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "body": { "type": "string" }, "payload": { "description": "Arbitrary jsonb, nullable.", "nullable": true }, "processingNote": { "type": "string", "nullable": true }, "deliveryState": { "type": "string", "enum": [ "pending_agent", "delivered" ] }, "contextId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredToAgentAt": { "type": "string", "format": "date-time", "nullable": true }, "hopCount": { "type": "integer" }, "replyToId": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "fromAgentId", "toAgentId", "body", "deliveryState", "contextId", "createdAt" ] }, "IntegrationCatalogEntry": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "authType": { "type": "string", "enum": [ "api_key", "oauth2", "mcp", "internal" ] }, "baseUrl": { "type": "string" }, "logo": { "type": "string" }, "description": { "type": "string", "nullable": true }, "docsUrl": { "type": "string", "nullable": true }, "keyHelp": { "type": "string", "nullable": true }, "secretLabel": { "type": "string", "nullable": true }, "configFields": { "type": "array", "description": "Connector-defined config field descriptors.", "items": { "type": "object", "additionalProperties": true } }, "oauthConfigured": { "type": "boolean", "nullable": true }, "apiKeyAlt": { "type": "boolean" }, "oauthSkipsConfig": { "type": "boolean" }, "availability": { "type": "string", "enum": [ "available", "coming_soon" ] }, "actions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "scope": { "type": "string" }, "description": { "type": "string" } } } } }, "required": [ "key", "name", "authType", "availability" ] }, "IntegrationConnection": { "type": "object", "description": "Never includes credential material.", "properties": { "id": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "providerKey": { "type": "string" }, "displayName": { "type": "string" }, "authType": { "type": "string", "enum": [ "api_key", "oauth2", "mcp", "internal" ] }, "status": { "type": "string", "enum": [ "active", "error", "revoked" ] }, "externalLabel": { "type": "string", "nullable": true }, "config": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdBy": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "providerKey", "displayName", "authType", "status", "createdAt" ] }, "IntegrationRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "toolName": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "planned", "done", "rejected" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "toolName", "status", "createdAt" ] }, "IntegrationGrant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "allowedTools": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string", "enum": [ "read", "write", "read_write" ] }, "constraints": { "type": "object", "nullable": true, "additionalProperties": true }, "grantedBy": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "connection": { "type": "object", "description": "Only present on the list endpoint (joined).", "properties": { "providerKey": { "type": "string" }, "displayName": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "error", "revoked" ] } } } }, "required": [ "id", "agentId", "connectionId", "scope", "createdAt" ] }, "IntegrationAuditLogEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "nullable": true }, "providerKey": { "type": "string" }, "toolKey": { "type": "string" }, "argsRedacted": { "type": "object", "nullable": true, "additionalProperties": true }, "status": { "type": "string", "enum": [ "ok", "denied", "error" ] }, "httpStatus": { "type": "integer", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "latencyMs": { "type": "integer", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "providerKey", "toolKey", "status", "createdAt" ] }, "SubscriptionPlanPrice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "planId": { "type": "string", "format": "uuid" }, "billingInterval": { "type": "string", "enum": [ "monthly", "annual" ] }, "pricePerAgentCents": { "type": "integer" }, "stripePriceId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "planId", "billingInterval", "pricePerAgentCents" ] }, "SubscriptionPlan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "creditsPerAgentPerMonth": { "type": "integer" }, "stripeProductId": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPlanPrice" } } }, "required": [ "id", "name", "active", "prices" ] }, "CompanySubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "planId": { "type": "string", "format": "uuid" }, "planPriceId": { "type": "string", "format": "uuid", "nullable": true }, "stripeSubscriptionId": { "type": "string", "nullable": true }, "stripeCustomerId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled" ] }, "currentPeriodStart": { "type": "string", "format": "date-time" }, "currentPeriodEnd": { "type": "string", "format": "date-time" }, "activeAgentsPurchased": { "type": "integer" }, "trialSource": { "type": "string", "enum": [ "self_serve", "admin_manual" ], "nullable": true }, "trialEndAgentCount": { "type": "integer", "nullable": true }, "planName": { "type": "string" }, "planDescription": { "type": "string" }, "creditsPerAgentPerMonth": { "type": "integer" }, "billingInterval": { "type": "string", "enum": [ "monthly", "annual" ], "nullable": true }, "pricePerAgentCents": { "type": "integer", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "companyId", "planId", "status", "activeAgentsPurchased" ] }, "CompanySubscriptionInfo": { "type": "object", "description": "Response of GET /subscriptions/company.", "properties": { "subscription": { "allOf": [ { "$ref": "#/components/schemas/CompanySubscription" } ], "nullable": true }, "memberRole": { "type": "string", "enum": [ "admin", "member" ] }, "activeSessionCount": { "type": "integer" }, "trialActivatedAt": { "type": "string", "format": "date-time", "nullable": true }, "pausedAgentCount": { "type": "integer" }, "trialDeletionAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "subscription", "memberRole", "activeSessionCount", "pausedAgentCount" ] }, "CreditBalance": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "includedBalance": { "type": "integer" }, "purchasedBalance": { "type": "integer" }, "currentPeriodStart": { "type": "string", "format": "date-time", "nullable": true }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" }, "consumedThisPeriod": { "type": "integer", "description": "Ledger sum of consumption transactions since currentPeriodStart (or the start of the current UTC calendar month)." } }, "required": [ "includedBalance", "purchasedBalance", "consumedThisPeriod" ] }, "CreditTransaction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "grant", "consumption", "purchase", "adjustment", "subscription_grant", "trial_grant" ] }, "amount": { "type": "integer", "description": "Signed: positive for grant/purchase, negative for consumption." }, "balanceAfterIncluded": { "type": "integer" }, "balanceAfterPurchased": { "type": "integer" }, "agentId": { "type": "string", "format": "uuid", "nullable": true }, "stripeInvoiceId": { "type": "string", "nullable": true }, "stripeCheckoutSessionId": { "type": "string", "nullable": true }, "adminUserId": { "type": "string", "format": "uuid", "nullable": true }, "note": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "companyId", "type", "amount", "createdAt" ] }, "CreditSubscription": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "stripeSubscriptionId": { "type": "string", "nullable": true }, "stripeCustomerId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled" ] }, "billingInterval": { "type": "string", "enum": [ "monthly", "annual" ] }, "creditsPerPeriod": { "type": "integer" }, "eurCentsPerCreditAtSubscription": { "type": "integer" }, "currentPeriodStart": { "type": "string", "format": "date-time" }, "currentPeriodEnd": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "StripeInvoiceSummary": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string", "nullable": true }, "created": { "type": "integer", "description": "Unix timestamp (seconds)." }, "amountPaid": { "type": "integer", "description": "Cents." }, "status": { "type": "string", "nullable": true }, "hostedInvoiceUrl": { "type": "string", "nullable": true }, "invoicePdf": { "type": "string", "nullable": true } }, "required": [ "id", "created", "amountPaid" ] }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true, "description": "E.164." }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "photo": { "type": "string", "nullable": true }, "timezone": { "type": "string", "description": "IANA timezone." }, "locale": { "type": "string", "nullable": true }, "banned": { "type": "boolean" }, "onboardingEmailsSent": { "type": "array", "items": { "type": "string" } }, "lastActiveAt": { "type": "string", "format": "date-time", "nullable": true }, "npsTriggeredAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "email", "timezone", "banned" ] }, "Company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "teamSize": { "type": "string", "enum": [ "solo", "under_10", "under_50", "under_150", "under_300", "over_300" ], "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "contextText": { "type": "string", "nullable": true }, "contextLinks": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } } } }, "allowModelSelection": { "type": "boolean" }, "allowByok": { "type": "boolean" }, "stripeCustomerId": { "type": "string", "nullable": true }, "trialActivatedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name" ] }, "CompanyInfo": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" }, "memberRole": { "type": "string", "enum": [ "admin", "member" ] }, "canCreateAgents": { "type": "boolean" }, "byokEnabled": { "type": "boolean" } }, "required": [ "company", "memberRole", "canCreateAgents" ] }, "CompanyMember": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "photo": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "canCreateAgents": { "type": "boolean" }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "teamName": { "type": "string", "nullable": true }, "joinedAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "name", "email", "role", "canCreateAgents" ] }, "CompanyMemberRow": { "type": "object", "description": "The raw `company_members` DB row — unlike `CompanyMember` (used by `GET /company/me/members`, which joins in the user's name/email/photo and the team's name), the three mutation endpoints below (`updateMemberRole`, `setMemberAgentPermission`, `setMemberTeam`) return this row as-is, with no join.", "properties": { "id": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "canCreateAgents": { "type": "boolean" }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "companyId", "userId", "role", "canCreateAgents", "createdAt" ] }, "CompanyInvitation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "token": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "cancelled" ] }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "invitedBy": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "email", "status", "expiresAt", "createdAt" ] }, "TeamPosition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "teamId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "parentId": { "type": "string", "format": "uuid", "nullable": true }, "agentId": { "type": "string", "format": "uuid", "nullable": true }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "agentInfo": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "image": { "type": "string" } } }, "memberInfo": { "type": "object", "nullable": true, "properties": { "userId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "photo": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "title", "createdAt" ] }, "Team": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "parentId": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/TeamPosition" } }, "liveAgentCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientId", "name", "positions", "liveAgentCount" ] }, "ApiKey": { "type": "object", "description": "Never carries the plaintext token (see ApiKeyCreated).", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "active": { "type": "boolean" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "keyPrefix", "active", "createdAt" ] }, "ApiKeyCreated": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" } ], "type": "object", "description": "Response of POST /users/api-keys — `token` is the plaintext aik_… key, shown once and never retrievable again.", "properties": { "token": { "type": "string", "description": "aik_… — store it now, it is never shown again." } }, "required": [ "token" ] }, "UseCase": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "department": { "type": "string", "enum": [ "sales", "marketing", "finance", "support", "hr", "it", "engineering", "product", "design" ] }, "title": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "description": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "aeoQuestion": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "aeoAnswer": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "toolsV2": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "description": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "integrationSlug": { "type": "string" } } } }, "workflowAgentSteps": { "type": "object", "description": "Same shape as LocalizedText, but each locale holds a string array.", "properties": { "fr": { "type": "array", "items": { "type": "string" } } }, "required": [ "fr" ], "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "workflowHumanSteps": { "type": "object", "description": "Same shape as LocalizedText, but each locale holds a string array.", "properties": { "fr": { "type": "array", "items": { "type": "string" } } }, "required": [ "fr" ], "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "faqV2": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "answer": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } } } } }, "coverImage": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "slug", "department", "title", "description" ] }, "IntegrationPage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "category": { "type": "string", "enum": [ "communication", "productivity", "projectManagement", "crmSales", "marketing", "devTools", "analytics", "aiTools", "finance", "hr", "support", "calendar" ] }, "logo": { "type": "string" }, "name": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "description": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "useCasesV2": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "description": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } } } } }, "stepsV2": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "description": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } } } } }, "faqV2": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "answer": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } } } } }, "coverImage": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "publishedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "slug", "category", "name", "description" ] }, "Article": { "type": "object", "description": "Shared shape for blog and news articles.", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "excerpt": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "content": { "type": "object", "description": "A French base value plus optional translations. `fr` is always present; other IETF locale keys are present when translated.", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "de": { "type": "string" }, "es": { "type": "string" }, "it": { "type": "string" }, "pt-BR": { "type": "string" }, "nl": { "type": "string" }, "pl": { "type": "string" }, "sv": { "type": "string" }, "da": { "type": "string" }, "tr": { "type": "string" }, "ja": { "type": "string" }, "ko": { "type": "string" } }, "required": [ "fr" ], "additionalProperties": { "type": "string" } }, "author": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "coverImage": { "type": "string", "nullable": true }, "publishedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "slug", "title", "excerpt", "content" ] } } }, "paths": { "/agents": { "get": { "operationId": "listAgents", "summary": "List your agents", "tags": [ "Agents" ], "responses": { "200": { "description": "Agents you own, plus agents on any team you belong to.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "createAgent", "summary": "Create an agent", "description": "Requires an active subscription and `canCreateAgents` permission. Guards, checked in order: AGENT_CREATION_NOT_ALLOWED (403), AGENT_LIMIT_REACHED (403), NO_ACTIVE_SUBSCRIPTION (402), MODEL_NOT_FOUND/HARNESS_NOT_FOUND (400), CLIENT_NOT_FOUND (404).", "tags": [ "Agents" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentBody" } } } }, "responses": { "201": { "description": "The created agent (raw row).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRecord" } } } }, "400": { "description": "Missing/invalid field, unknown model/harness, or invalid engine.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_ACTIVE_SUBSCRIPTION", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "AGENT_CREATION_NOT_ALLOWED / NOT_TEAM_MEMBER / AGENT_LIMIT_REACHED / BYOK_DISABLED / BYOK_NOT_ALLOWED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CLIENT_NOT_FOUND / PROVIDER_KEY_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}": { "get": { "operationId": "getAgent", "summary": "Get agent detail", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDetail" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/cancel": { "post": { "operationId": "cancelAgent", "summary": "Cancel a provisioning agent", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_CANCELLABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/retry-provisioning": { "post": { "operationId": "retryAgentProvisioning", "summary": "Retry a failed provisioning", "description": "Owner-only. Re-dispatches provisioning with the engine's current release and a fresh bootstrap token.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_ACTIVE_SUBSCRIPTION", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_RETRYABLE / AGENT_LIMIT_REACHED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/end": { "post": { "operationId": "endAgent", "summary": "End an active agent", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/AgentRecord" } }, "required": [ "session" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_ACTIVE — agent already ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/resume": { "post": { "operationId": "resumeAgent", "summary": "Resume a paused agent", "description": "Trial-end lifecycle. Same company-membership + canCreateAgents gate as agent creation.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_ACTIVE_SUBSCRIPTION", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "AGENT_CREATION_NOT_ALLOWED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_PAUSED / AGENT_LIMIT_REACHED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/upgrade-status": { "get": { "operationId": "getAgentUpgradeStatus", "summary": "Check whether an engine upgrade is available", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeStatus" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/upgrade": { "post": { "operationId": "upgradeAgent", "summary": "Trigger an in-place engine image upgrade", "description": "State preserved, brief downtime. 409 if the agent is not active.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "engineVersion": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_ACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Orchestrator dispatch failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/agent-token": { "post": { "operationId": "issueAgentToken", "summary": "Issue or rotate the agent's own auth token", "description": "Used by the orchestrator/SDK to authenticate the agent-SDK plane (/agent/*), not by this customer API itself.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "UNAUTHORIZED — caller is not the owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_ACTIVATABLE — agent already completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/name": { "patch": { "operationId": "renameAgent", "summary": "Set the agent's display name", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "400": { "description": "name must be a non-empty string", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/team": { "patch": { "operationId": "setAgentTeam", "summary": "Move the agent to a team, or make it personal", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId" ], "properties": { "teamId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "nullable": true }, "scope": { "type": "string", "enum": [ "personal", "team" ] } } } } } }, "400": { "description": "teamId must be a string or null", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "NOT_TEAM_MEMBER", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/llm-key": { "patch": { "operationId": "setAgentLlmKey", "summary": "Reassign the agent's BYOK LLM key", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "llmKeyId" ], "properties": { "llmKeyId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "llmKeyId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "400": { "description": "llmKeyId must be a string or null / PROVIDER_KEY_INVALID / DIRECT_PROVIDER_REASSIGNMENT_NOT_SUPPORTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "BYOK_DISABLED / BYOK_NOT_ALLOWED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/provision": { "post": { "operationId": "devProvisionAgent", "summary": "Dev helper: simulate agent activation directly", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "clientTimezone": { "type": "string" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_ACTIVATABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/messages": { "get": { "operationId": "listMessages", "summary": "List an agent's chat messages", "tags": [ "Messages" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "sendMessage", "summary": "Send a chat message to the agent", "description": "Fire-and-forget: the reply arrives later over the WS bridge → SSE/DB. `role` is ignored — always inserted as `user`.", "tags": [ "Messages" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "content required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/messages/{messageId}/flag": { "post": { "operationId": "flagMessage", "summary": "Flag a message as an error (admin review queue)", "tags": [ "Messages" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "description": "Message id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/events": { "get": { "operationId": "streamAgentEvents", "summary": "SSE stream of new messages and live-activity events", "description": "Not a JSON response: `Content-Type: text/event-stream`. Emits `message`, `typing`, `heartbeat`, `activity`, `activity_state`, and `message_delta` events. Kept alive with `: ping` comments.", "tags": [ "Messages" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "text/event-stream — no fixed JSON schema.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/activity": { "get": { "operationId": "listActivity", "summary": "Live-activity feed history", "tags": [ "Activity" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "Newest-first page cursor.", "schema": { "type": "string", "format": "date-time" } }, { "name": "after", "in": "query", "required": false, "description": "Oldest-first, SSE-resume mode.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Chat-origin events are scoped to the caller's own conversation; cron/subagent/system/integration events are agent-wide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEvent" } } }, "required": [ "events" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/activity/state": { "get": { "operationId": "getActivityState", "summary": "Current working/idle state", "tags": [ "Activity" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityState" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/models": { "get": { "operationId": "listModels", "summary": "List visible AI models (for the create-agent form)", "tags": [ "Agent Options" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AiModel" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/harnesses": { "get": { "operationId": "listHarnesses", "summary": "List visible harnesses (for the create-agent form)", "tags": [ "Agent Options" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Harness" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List your programmatic API keys", "description": "Company-admin only.", "tags": [ "API Keys" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "createApiKey", "summary": "Create an API key", "description": "Company-admin only. The plaintext token is returned once.", "tags": [ "API Keys" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" } } } }, "400": { "description": "name required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users/api-keys/{id}": { "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "description": "Company-admin only.", "tags": [ "API Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/files": { "get": { "operationId": "listAgentAccessibleFiles", "summary": "List files an agent can access (granted files + its dedicated folder)", "tags": [ "Files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileNode" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/files/{nodeId}/download-url": { "get": { "operationId": "getAgentFileDownloadUrl", "summary": "Get a signed download URL for a file accessible to the agent", "tags": [ "Files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "nodeId", "in": "path", "required": true, "description": "File node id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedDownloadUrl" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/client/files": { "get": { "operationId": "listClientFiles", "summary": "List your own file tree", "tags": [ "Files" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileNode" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/client/files/folders": { "post": { "operationId": "createFolder", "summary": "Create a folder", "tags": [ "Files" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "parentId": { "type": "string", "format": "uuid" }, "agentTag": { "type": "string", "format": "uuid", "description": "Tags the folder as belonging to an agent's dedicated space." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileNode" } } } }, "400": { "description": "name required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "parentId not found/owned, or agentTag not owned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/client/files/nodes": { "post": { "operationId": "createFileNode", "summary": "Create a file node (before uploading)", "tags": [ "Files" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "parentId": { "type": "string", "format": "uuid" }, "agentTag": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileNode" } } } }, "400": { "description": "name required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "parentId not found/owned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/client/files/{nodeId}": { "patch": { "operationId": "renameFileNode", "summary": "Rename a file or folder", "tags": [ "Files" ], "parameters": [ { "name": "nodeId", "in": "path", "required": true, "description": "File node id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileNode" } } } }, "400": { "description": "name required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "deleteFileNode", "summary": "Delete a file or folder (recursive)", "tags": [ "Files" ], "parameters": [ { "name": "nodeId", "in": "path", "required": true, "description": "File node id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/client/files/{nodeId}/upload-url": { "post": { "operationId": "getFileUploadUrl", "summary": "Get a signed upload URL for a file node", "tags": [ "Files" ], "parameters": [ { "name": "nodeId", "in": "path", "required": true, "description": "File node id (must be type file)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedUploadUrl" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/client/files/{nodeId}/download-url": { "get": { "operationId": "getFileDownloadUrl", "summary": "Get a signed download URL for a file node", "tags": [ "Files" ], "parameters": [ { "name": "nodeId", "in": "path", "required": true, "description": "File node id (must be type file)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedDownloadUrl" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/client/files/{nodeId}/complete-upload": { "post": { "operationId": "completeFileUpload", "summary": "Finalize an upload", "tags": [ "Files" ], "parameters": [ { "name": "nodeId", "in": "path", "required": true, "description": "File node id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "storagePath", "fileSize", "mimeType" ], "properties": { "storagePath": { "type": "string" }, "fileSize": { "type": "integer" }, "mimeType": { "type": "string" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileNode" } } } }, "400": { "description": "storagePath, fileSize, mimeType required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/file-grants": { "get": { "operationId": "listFileGrants", "summary": "List client files granted to an agent", "tags": [ "Files" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileGrant" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "grantFiles", "summary": "Grant client files to an agent", "tags": [ "Files" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "nodeIds" ], "properties": { "nodeIds": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "201": { "description": "Newly inserted grants (already-granted nodeIds are silently skipped, so the array may be shorter than the request, even empty).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileGrant" } } } } }, "400": { "description": "nodeIds array required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/file-grants/{grantId}": { "delete": { "operationId": "revokeFileGrant", "summary": "Revoke a file grant", "tags": [ "Files" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "grantId", "in": "path", "required": true, "description": "Grant id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/file-grants/dedicated-folder": { "post": { "operationId": "createDedicatedFolder", "summary": "Create (or return) the agent's dedicated agent-writable folder", "tags": [ "Files" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The dedicated folder already existed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedicatedFolderResult" } } } }, "201": { "description": "The dedicated folder was just created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedicatedFolderResult" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/cron-jobs": { "get": { "operationId": "listCronJobs", "summary": "List cron jobs created by the agent", "description": "Active jobs first (by createdAt), then archived (by archivedAt desc). Each job carries up to 20 recent executions.", "tags": [ "Cron Jobs" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CronJobsResponse" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/sub-agents": { "get": { "operationId": "listSubAgents", "summary": "List sub-agents spawned by the agent", "tags": [ "Sub-Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubAgent" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/agent-messages": { "get": { "operationId": "listInteragentMessages", "summary": "List inter-agent messages sent/received by this agent", "tags": [ "Interagent Messages" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Omit for both.", "schema": { "type": "string", "enum": [ "sent", "received" ] } }, { "name": "before", "in": "query", "required": false, "description": "Pagination cursor.", "schema": { "type": "string", "format": "date-time" } }, { "name": "beforeId", "in": "query", "required": false, "description": "Pagination tie-breaker.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "contextId", "in": "query", "required": false, "description": "Filter to one conversation thread.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "channelEnabled": { "type": "boolean" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InteragentMessageListItem" } } }, "required": [ "channelEnabled", "messages" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/agent-messages/{id}": { "get": { "operationId": "getInteragentMessage", "summary": "Get an inter-agent message and its thread", "tags": [ "Interagent Messages" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Message id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/InteragentMessageDetail" }, "thread": { "type": "array", "items": { "$ref": "#/components/schemas/InteragentMessageDetail" } } }, "required": [ "message", "thread" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/integrations": { "post": { "operationId": "requestIntegration", "summary": "Request a new (not-yet-available) integration", "tags": [ "Integrations" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "toolName" ], "properties": { "toolName": { "type": "string", "minLength": 1 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationRequest" } } } }, "400": { "description": "toolName required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/integrations/catalog": { "get": { "operationId": "listIntegrationCatalog", "summary": "List available/coming-soon connectors", "tags": [ "Integrations" ], "parameters": [ { "name": "locale", "in": "query", "required": false, "description": "'fr' for French text fields, else English.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationCatalogEntry" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/integrations/{key}/interest": { "post": { "operationId": "registerIntegrationInterest", "summary": "Register interest in a coming-soon connector", "description": "Idempotent — a repeat call returns the existing request.", "tags": [ "Integrations" ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Connector key", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationRequest" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/integrations/connections": { "get": { "operationId": "listIntegrationConnections", "summary": "List your company's integration connections", "tags": [ "Integrations" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationConnection" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "createIntegrationConnection", "summary": "Connect an integration via a pasted API key/secret", "description": "For OAuth2 connectors without `apiKeyAlt`, use POST /integrations/oauth/{provider}/start instead.", "tags": [ "Integrations" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerKey" ], "properties": { "providerKey": { "type": "string" }, "displayName": { "type": "string" }, "secret": { "type": "string", "description": "Required unless the connector's authType is internal." }, "externalLabel": { "type": "string", "nullable": true }, "config": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationConnection" } } } }, "400": { "description": "providerKey required / not_connectable / no_company / oauth_required / secret_required / config_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "github_not_connected — the \"code\" internal capability requires an active GitHub connection first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/integrations/connections/{id}": { "delete": { "operationId": "revokeIntegrationConnection", "summary": "Revoke an integration connection", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Connection id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/integrations/oauth/{provider}/start": { "post": { "operationId": "startIntegrationOAuth", "summary": "Start an OAuth2 connection flow", "description": "Returns the provider authorize URL to redirect the browser to.", "tags": [ "Integrations" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Connector key", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Required unless the connector skips config fields for OAuth." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "400": { "description": "config_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_provider — not found, or not an oauth2 connector.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "oauth_not_configured — the platform OAuth app credentials are not provisioned for this connector.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/integrations/oauth/callback": { "get": { "operationId": "integrationOAuthCallback", "summary": "OAuth2 provider redirect callback", "description": "Public / session-less — called by the OAuth provider's browser redirect. Authenticity comes from the signed `state` param (10-minute TTL), never from a bearer token. Always responds with an HTTP redirect to the web app's Settings > Integrations page (`?connected=` on success, `?error=oauth_denied|oauth_invalid_state|oauth_exchange_failed` on failure) — never a JSON body.", "tags": [ "Integrations" ], "parameters": [ { "name": "code", "in": "query", "required": false, "description": "Authorization code from the provider.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Signed state token from the /start call.", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Set by the provider when the user denies access.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the web app; see description for the query params it carries." } }, "security": [] } }, "/agents/{agentId}/integration-grants": { "get": { "operationId": "listIntegrationGrants", "summary": "List integration grants for an agent", "tags": [ "Integrations" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationGrant" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "grantIntegration", "summary": "Grant (or update) an agent's access to an integration connection", "description": "Upsert on (agentId, connectionId). `providerKey: \"code\"` substitutes for `connectionId` for the internal code capability.", "tags": [ "Integrations" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid" }, "providerKey": { "type": "string", "description": "\"code\" is the one value that substitutes for connectionId." }, "allowedTools": { "type": "array", "items": { "type": "string" }, "description": "Filtered server-side to valid connector actions." }, "scope": { "type": "string", "enum": [ "read", "write", "read_write" ], "default": "read" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "constraints": { "type": "object", "nullable": true, "additionalProperties": true } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationGrant" } } } }, "400": { "description": "connectionId required / no_company / connection_not_found / unknown_provider / no_valid_tools", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — agent not owned by caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/integration-grants/{grantId}": { "patch": { "operationId": "updateIntegrationGrant", "summary": "Update an integration grant's constraints", "tags": [ "Integrations" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "grantId", "in": "path", "required": true, "description": "Grant id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "constraints" ], "properties": { "constraints": { "type": "object", "nullable": true, "additionalProperties": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationGrant" } } } }, "400": { "description": "constraints must be an object or null", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "revokeIntegrationGrant", "summary": "Revoke an integration grant", "tags": [ "Integrations" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "grantId", "in": "path", "required": true, "description": "Grant id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agentId}/integration-activity": { "get": { "operationId": "getAgentIntegrationActivity", "summary": "Recent integration/tool call audit log for an agent", "tags": [ "Integrations" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Most recent 100, newest first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationAuditLogEntry" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/plans": { "get": { "operationId": "listSubscriptionPlans", "summary": "List active subscription plans", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPlan" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/company": { "get": { "operationId": "getCompanySubscription", "summary": "Get your company's subscription", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySubscriptionInfo" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "createCompanySubscription", "summary": "Subscribe your company to a plan", "description": "Company-admin only. Requires the company's Stripe customer to already have a card on file unless USE_STRIPE=false.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "planId", "priceId" ], "properties": { "planId": { "type": "string", "format": "uuid" }, "priceId": { "type": "string", "format": "uuid" }, "activeAgentsPurchased": { "type": "integer", "minimum": 1, "default": 1 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySubscription" } } } }, "400": { "description": "planId/priceId required, or activeAgentsPurchased must be a positive integer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "PAYMENT_METHOD_REQUIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / Plan not found / Price not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Company already has a subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "operationId": "updateCompanySubscription", "summary": "Change plan/price or seat count", "description": "Company-admin only.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string", "format": "uuid" }, "priceId": { "type": "string", "format": "uuid" }, "activeAgentsPurchased": { "type": "integer" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySubscription" } } } }, "400": { "description": "Plan downgrade not allowed while active / session count cannot be decreased", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / No active subscription / Plan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "cancelCompanySubscription", "summary": "Cancel your company's subscription", "description": "Company-admin only.", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySubscription" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / No active subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/checkout": { "post": { "operationId": "createSubscriptionCheckout", "summary": "Create a Stripe Checkout session for a new subscription", "description": "Company-admin only. With USE_STRIPE=false, creates the subscription directly and returns `url: null`.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "planId", "priceId" ], "properties": { "planId": { "type": "string", "format": "uuid" }, "priceId": { "type": "string", "format": "uuid" }, "activeAgentsPurchased": { "type": "integer", "default": 1 }, "creditsPerPeriod": { "type": "integer", "minimum": 1000, "maximum": 50000 }, "billingInterval": { "type": "string", "enum": [ "monthly", "annual" ], "description": "Required when creditsPerPeriod is set." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] }, { "type": "object", "properties": { "url": { "type": "null" }, "subscription": { "$ref": "#/components/schemas/CompanySubscription" } }, "required": [ "url", "subscription" ] } ] } } } }, "400": { "description": "Invalid input, or PLAN_PRICE_NOT_CONFIGURED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / Plan not found / Price not found / Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Company already has a subscription (dev mode only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/checkout/add-sessions": { "post": { "operationId": "addSubscriptionSeats", "summary": "Add seats to an existing subscription", "description": "Company-admin only.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "additionalSessions" ], "properties": { "additionalSessions": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceUrl": { "type": "string", "nullable": true }, "activeAgentsPurchased": { "type": "integer" } } } } } }, "400": { "description": "additionalSessions must be a positive integer / Subscription is canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / No active subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Stripe subscription has no line items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/agents/reduce": { "post": { "operationId": "reduceSubscriptionSeats", "summary": "Reduce purchased seats immediately", "description": "Company-admin only.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "activeAgentsPurchased": { "type": "integer" }, "effect": { "type": "string", "enum": [ "immediate" ] }, "alreadyApplied": { "type": "boolean" } } } } } }, "400": { "description": "count must be a positive integer / AGENTS_STILL_ACTIVE / NOT_A_REDUCTION", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / No active subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Stripe subscription has no line items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/checkout/verify": { "post": { "operationId": "verifySubscriptionCheckout", "summary": "Sync the subscription with Stripe after a Checkout redirect", "description": "Idempotent.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId" ], "properties": { "sessionId": { "type": "string" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySubscription" } } } }, "400": { "description": "sessionId required / Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized — Checkout session belongs to another company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed to retrieve the Stripe session/subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/invoices": { "get": { "operationId": "listInvoices", "summary": "List Stripe invoices for your company", "description": "Company-admin only. `[]` if no Stripe customer or USE_STRIPE=false.", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StripeInvoiceSummary" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/portal": { "get": { "operationId": "getBillingPortalUrl", "summary": "Get a Stripe billing portal URL", "description": "Company-admin only.", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / No billing account yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/credits/balance": { "get": { "operationId": "getCreditBalance", "summary": "Get your company's credit balance", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalance" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/credits/transactions": { "get": { "operationId": "listCreditTransactions", "summary": "Paginated credit ledger", "tags": [ "Subscriptions" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTransaction" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/credits/checkout": { "post": { "operationId": "createCreditsCheckout", "summary": "Buy a one-time credits top-up", "description": "Company-admin only.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "credits" ], "properties": { "credits": { "type": "integer", "minimum": 1000, "maximum": 50000 }, "locale": { "type": "string" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] }, { "type": "object", "properties": { "url": { "type": "null" }, "balance": { "$ref": "#/components/schemas/CreditBalance" } }, "required": [ "url", "balance" ] } ] } } } }, "400": { "description": "credits must be an integer between 1000 and 50000", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/credits/subscription": { "get": { "operationId": "getCreditSubscription", "summary": "Get your company's recurring credit subscription", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "null if none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditSubscription" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "operationId": "updateCreditSubscription", "summary": "Change the recurring credit amount", "description": "Company-admin only. The billing interval is fixed after creation.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "creditsPerPeriod" ], "properties": { "creditsPerPeriod": { "type": "integer", "minimum": 1000, "maximum": 50000 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditSubscription" } } } }, "400": { "description": "creditsPerPeriod must be an integer between 1000 and 50000", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / No active credit subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "cancelCreditSubscription", "summary": "Cancel the recurring credit subscription", "description": "Company-admin only.", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditSubscription" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / No active credit subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/credits/subscription/checkout": { "post": { "operationId": "createCreditSubscriptionCheckout", "summary": "Start a recurring credit subscription", "description": "Company-admin only. No trial period.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "creditsPerPeriod", "billingInterval" ], "properties": { "creditsPerPeriod": { "type": "integer", "minimum": 1000, "maximum": 50000 }, "billingInterval": { "type": "string", "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "nullable": true }, "subscription": { "$ref": "#/components/schemas/CreditSubscription" } } } } } }, "400": { "description": "Invalid creditsPerPeriod/billingInterval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company / Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Company already has an active credit subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/subscriptions/trial/activate": { "post": { "operationId": "activateTrial", "summary": "Activate the self-serve 14-day trial", "description": "Company-admin only. Grants 3 agent seats. May require phone verification.", "tags": [ "Subscriptions" ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySubscription" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only / Phone not verified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Trial already used / Company already has a subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "No plan configured for the trial.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users/me": { "get": { "operationId": "getMe", "summary": "Get your user profile", "tags": [ "Users" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "upsertMe", "summary": "Upsert your user profile (call on first login)", "description": "May create a company if `company`/`teamSize` are provided. Phone is normalized to E.164 and silently dropped if unparsable — never blocks signup.", "tags": [ "Users" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "company": { "type": "string" }, "phone": { "type": "string" }, "teamSize": { "type": "string", "enum": [ "solo", "under_10", "under_50", "under_150", "under_300", "over_300" ] }, "timezone": { "type": "string", "description": "IANA timezone." }, "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "PHONE_EXISTS — account/company still created, just without the phone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "operationId": "updateMe", "summary": "Update your user profile", "tags": [ "Users" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "photo": { "type": "string", "format": "uri", "nullable": true }, "timezone": { "type": "string" }, "phone": { "type": "string", "nullable": true, "description": "null clears it." }, "locale": { "type": "string" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Validation error / PHONE_INVALID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "PHONE_EXISTS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "deleteMe", "summary": "Self-service account deletion (GDPR)", "tags": [ "Users" ], "requestBody": { "description": "", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "deleteCompany": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "companyDeleted": { "type": "boolean" }, "authDeleteFailures": { "type": "integer" } }, "required": [ "ok", "companyDeleted", "authDeleteFailures" ] } } } }, "400": { "description": "LAST_ADMIN_OF_COMPANY (carries companyName, agentCount) / ACTIVE_SUBSCRIPTION / validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users/intercom-token": { "get": { "operationId": "getIntercomToken", "summary": "Get a signed Intercom identity token", "tags": [ "Users" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Intercom not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/company/me": { "get": { "operationId": "getCompany", "summary": "Get your company", "tags": [ "Company" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInfo" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "operationId": "updateCompany", "summary": "Update company name / context", "description": "Company-admin only.", "tags": [ "Company" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "logoUrl": { "type": "string", "format": "uri", "nullable": true }, "contextText": { "type": "string", "maxLength": 5000, "nullable": true }, "contextLinks": { "type": "array", "maxItems": 20, "nullable": true, "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/company/me/logo": { "post": { "operationId": "uploadCompanyLogo", "summary": "Upload the company logo", "description": "Company-admin only. multipart/form-data, image, max 5MB.", "tags": [ "Company" ], "requestBody": { "description": "", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicUrl": { "type": "string", "format": "uri" } }, "required": [ "publicUrl" ] } } } }, "400": { "description": "No file provided / Invalid file type / File too large (max 5MB)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/company/me/members": { "get": { "operationId": "listCompanyMembers", "summary": "List company members", "tags": [ "Company" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyMember" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/company/me/members/{userId}": { "patch": { "operationId": "updateMemberRole", "summary": "Change a member's role", "description": "Company-admin only.", "tags": [ "Company" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "Member user id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "admin", "member" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemberRow" } } } }, "400": { "description": "Validation error / LAST_ADMIN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found / Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "removeMember", "summary": "Remove a member from the company", "description": "Company-admin only.", "tags": [ "Company" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "Member user id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "LAST_ADMIN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found / Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/company/me/members/{userId}/agent-permission": { "patch": { "operationId": "setMemberAgentPermission", "summary": "Set whether a member can create agents", "description": "Company-admin only.", "tags": [ "Company" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "Member user id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "canCreateAgents" ], "properties": { "canCreateAgents": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemberRow" } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "No active subscription, or subscription not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found / Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/company/me/members/{userId}/team": { "patch": { "operationId": "setMemberTeam", "summary": "Move a member to a different team", "description": "Company-admin only.", "tags": [ "Company" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "Member user id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId" ], "properties": { "teamId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemberRow" } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found / Team not found / Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/company/me/invitations": { "get": { "operationId": "listInvitations", "summary": "List pending invitations", "description": "Company-admin only.", "tags": [ "Company" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyInvitation" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "inviteMember", "summary": "Invite a member by email", "description": "Company-admin only. 7-day expiry. Emails a direct durable-token link (no Supabase one-time link).", "tags": [ "Company" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInvitation" } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ALREADY_MEMBER / ALREADY_INVITED / USER_IN_OTHER_COMPANY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/company/me/invitations/{id}": { "delete": { "operationId": "cancelInvitation", "summary": "Cancel a pending invitation", "description": "Company-admin only.", "tags": [ "Company" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invitation id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found / Invitation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/company/invitations/accept": { "post": { "operationId": "acceptInvitation", "summary": "Accept a company invitation", "description": "The caller's authenticated email must match the invitation's email.", "tags": [ "Company" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" } }, "required": [ "companyId" ] } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid invitation / expired or already used / email mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/teams": { "get": { "operationId": "listTeams", "summary": "List your company's teams (org chart)", "description": "All company members can view. Falls back to just your own teams if you have no company.", "tags": [ "Teams" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "createTeam", "summary": "Create a team", "description": "Company-admin only (or no company, for a personal team).", "tags": [ "Teams" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "parentId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Validation error / TEAM_CROSS_COMPANY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller does not have the required role/permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "parentId not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/teams/mine": { "get": { "operationId": "listMyTeams", "summary": "List teams you own or hold a position in", "tags": [ "Teams" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/teams/{id}": { "get": { "operationId": "getTeam", "summary": "Get team detail", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "operationId": "updateTeam", "summary": "Update a team", "description": "Company admin (of the team's company) or the team's own creator.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "parentId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Validation error / TEAM_CYCLE / TEAM_CROSS_COMPANY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "deleteTeam", "summary": "Delete a team", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "TEAM_HAS_CHILDREN / TEAM_HAS_LIVE_AGENTS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/teams/{id}/positions": { "post": { "operationId": "createTeamPosition", "summary": "Add an org-chart position to a team", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "parentId": { "type": "string", "format": "uuid", "nullable": true }, "agentId": { "type": "string", "format": "uuid", "nullable": true, "description": "Assigning an agent moves it into this team." }, "userId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamPosition" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/teams/{id}/positions/{positionId}": { "put": { "operationId": "updateTeamPosition", "summary": "Update an org-chart position", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "string" } }, { "name": "positionId", "in": "path", "required": true, "description": "Position id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "parentId": { "type": "string", "format": "uuid", "nullable": true }, "agentId": { "type": "string", "format": "uuid", "nullable": true }, "userId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamPosition" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "deleteTeamPosition", "summary": "Delete an org-chart position", "description": "No cascade — fails if the position still has child positions.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "string" } }, { "name": "positionId", "in": "path", "required": true, "description": "Position id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or the caller is not authorized to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "POSITION_HAS_CHILDREN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/plans": { "get": { "operationId": "publicListPlans", "summary": "List active subscription plans (public pricing page)", "tags": [ "Public" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPlan" } } } } } }, "security": [] } }, "/public/credit-rate": { "get": { "operationId": "publicGetCreditRate", "summary": "Get the public €→credits conversion rate", "tags": [ "Public" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "eurCentsPerCredit": { "type": "number" } }, "required": [ "eurCentsPerCredit" ] } } } } }, "security": [] } }, "/public/invitations/{token}": { "get": { "operationId": "publicPreviewInvitation", "summary": "Preview a company invitation", "description": "Used by the accept-invite page. Strict per-IP rate limit.", "tags": [ "Public" ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Invitation token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "workspaceName": { "type": "string" } }, "required": [ "email", "workspaceName" ] } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "already_used / expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "too_many_requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/public/newsletter": { "post": { "operationId": "publicSubscribeNewsletter", "summary": "Subscribe an email to the newsletter", "description": "Upserts — resubmitting the same email still returns 201. Strict per-IP rate limit.", "tags": [ "Public" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "invalid_email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "too_many_requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/public/email-exists": { "post": { "operationId": "publicEmailExists", "summary": "Check whether an account already exists for an email", "description": "Used by /signup before sending an OTP. Strict per-IP rate limit.", "tags": [ "Public" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "exists": { "type": "boolean" } }, "required": [ "exists" ] } } } }, "400": { "description": "invalid_email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "too_many_requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/use-cases": { "get": { "operationId": "listUseCases", "summary": "List published use cases", "tags": [ "Marketing Content" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "default": 0 } }, { "name": "department", "in": "query", "required": false, "description": "Invalid values are ignored, not rejected.", "schema": { "type": "string", "enum": [ "sales", "marketing", "finance", "support", "hr", "it", "engineering", "product", "design" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UseCase" } } } } } }, "security": [] } }, "/use-cases/{slug}": { "get": { "operationId": "getUseCase", "summary": "Get a published use case", "tags": [ "Marketing Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Use case slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UseCase" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/integration-pages": { "get": { "operationId": "listIntegrationPages", "summary": "List published integration marketing pages", "tags": [ "Marketing Content" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "default": 0 } }, { "name": "category", "in": "query", "required": false, "description": "Invalid values are ignored, not rejected.", "schema": { "type": "string", "enum": [ "communication", "productivity", "projectManagement", "crmSales", "marketing", "devTools", "analytics", "aiTools", "finance", "hr", "support", "calendar" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationPage" } } } } } }, "security": [] } }, "/integration-pages/{slug}": { "get": { "operationId": "getIntegrationPage", "summary": "Get a published integration marketing page", "tags": [ "Marketing Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Integration page slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationPage" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/integration-pages/{slug}/related-use-cases": { "get": { "operationId": "getRelatedUseCases", "summary": "Published use cases that reference this integration", "description": "Up to 8. Returns `[]`, never 404, if the integration slug itself doesn't exist.", "tags": [ "Marketing Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Integration page slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UseCase" } } } } } }, "security": [] } }, "/blog": { "get": { "operationId": "listBlogArticles", "summary": "List published blog articles", "tags": [ "Marketing Content" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } } } } } }, "security": [] } }, "/blog/{slug}": { "get": { "operationId": "getBlogArticle", "summary": "Get a published blog article", "tags": [ "Marketing Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Article slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/news": { "get": { "operationId": "listNewsArticles", "summary": "List published news articles", "tags": [ "Marketing Content" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } } } } } }, "security": [] } }, "/news/{slug}": { "get": { "operationId": "getNewsArticle", "summary": "Get a published news article", "tags": [ "Marketing Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Article slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } } } }