{ "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, within the limits of the key:\n\n- **Scope** — a `read` key can only call GET operations (any other verb: `403 API_KEY_READ_ONLY`); a `write` key can call everything its user can, except the operations below.\n- **Forbidden to every key** — billing changes (every non-GET `/subscriptions/*`), minting agent tokens, listing or managing API keys (every `/users/api-keys` operation), deleting the account: `403 API_KEY_FORBIDDEN`. These need a signed-in user in the app.\n- **Expiry** — optional (30, 90 or 365 days); an expired key gets `401 API_KEY_EXPIRED`.\n\nEach operation carries `x-atako-api-key: read | write | forbidden` — the minimum key scope it needs, or `forbidden`.\n\n## Live events\n\n`GET /notifications/sse` and `GET /agents/{agentId}/events` are Server-Sent Events streams (`text/event-stream`), authenticated with the same Bearer header — an API key works.\n\n## Uploading a file\n\nTwo steps: `POST /client/files/nodes` then `POST /client/files/{nodeId}/upload-url` return a signed storage URL; `PUT` the raw bytes to it, then call `POST /client/files/{nodeId}/complete-upload`. Grant it to an agent with `POST /agents/{agentId}/file-grants`.\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 the same capabilities as Model Context Protocol tools for AI clients (Claude Code, Claude Desktop, Cursor, ChatGPT), grouped in toolsets (`/mcp?toolsets=projects,agents`); a `read` key only gets read-only tools. 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": "Floor" }, { "name": "Search" }, { "name": "Notices" }, { "name": "Organization" }, { "name": "Projects" }, { "name": "Notifications" }, { "name": "Agent Shared Items" }, { "name": "Agent Email" }, { "name": "Agent Webhooks" }, { "name": "Company Dashboard" }, { "name": "LLM Provider Keys" }, { "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", "opencode" ] }, "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." }, "modelName": { "type": "string", "nullable": true, "description": "Display name of the agent's OpenRouter-catalogue model (ai_models.name); null for a direct-provider agent (see directModelId) or an agent left on the platform default." }, "harnessName": { "type": "string", "nullable": true, "description": "Display name of the agent's harness (harnesses.name); null when no harness was picked at creation — the runtime `engine` below is then the only harness." }, "engine": { "type": "string", "enum": [ "openclaw", "hermes", "opencode" ] }, "engineVersion": { "type": "string", "nullable": true }, "engineRequestedVersion": { "type": "string", "nullable": true }, "machineLost": { "type": "boolean" }, "activity": { "$ref": "#/components/schemas/ActivitySummary" }, "mission": { "type": "string", "nullable": true, "description": "The agent's mission (1–3 sentences). Present only when the caller can administer the agent (`canManage`)." }, "systemPrompt": { "type": "string", "nullable": true, "description": "The agent's raw instructions. Present only when the caller can administer the agent." }, "clientContext": { "type": "string", "nullable": true, "description": "Per-agent business context. Present only when the caller can administer the agent." } }, "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, "description": "Raw user instructions (no business context appended)." }, "mission": { "type": "string", "nullable": true }, "profileUpdatedAt": { "type": "string", "format": "date-time" }, "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", "opencode" ] }, "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/." }, "mission": { "type": "string", "nullable": true, "maxLength": 20000, "description": "The agent's mission in 1–3 sentences, trimmed." }, "systemPrompt": { "type": "string", "nullable": true, "maxLength": 20000, "description": "Free-text agent instructions, trimmed. Stored and sent to the orchestrator as-is (no business context appended)." }, "clientContext": { "type": "string", "nullable": true, "maxLength": 20000, "description": "Free-text per-agent business context, trimmed. Kept in its own column." }, "modelId": { "type": "string", "description": "Either an `ai_models` UUID (from GET /models or `aiModelId` in GET /models/catalog) or a raw OpenRouter slug (`slug` in GET /models/catalog, e.g. \"mistralai/mistral-small\"). A slug unknown to the catalog is rejected with 400. Omitted → admin-declared default model. With a direct-provider BYOK key (openai/anthropic), this is instead the provider's own model id.", "example": "anthropic/claude-sonnet-4" }, "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", "opencode" ], "description": "Defaults to the platform default engine (hermes). `opencode` additionally requires `allowedRepos`." }, "allowedRepos": { "type": "array", "items": { "type": "string" }, "description": "Repositories (`owner/repo`) the agent may work on. REQUIRED (≥1) for `engine: opencode`, which also requires an active company GitHub connection; ignored by the other engines." }, "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" } }, "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" ] }, "CatalogModel": { "type": "object", "required": [ "slug", "name", "provider", "providerLabel", "suggested", "isDefault" ], "properties": { "slug": { "type": "string", "description": "OpenRouter model id, e.g. \"anthropic/claude-sonnet-4\"." }, "name": { "type": "string", "description": "OpenRouter display name, e.g. \"Anthropic: Claude Sonnet 4\"." }, "provider": { "type": "string", "description": "Slug prefix before '/'." }, "providerLabel": { "type": "string", "description": "Human label — the name prefix before ':', else the capitalized provider." }, "description": { "type": "string", "nullable": true }, "contextLength": { "type": "integer", "nullable": true, "description": "No provider pricing is exposed to clients: Atako sells inference at its own rate." }, "suggested": { "type": "boolean", "description": "Recommended by Atako (`ai_models.visible`)." }, "isDefault": { "type": "boolean", "description": "Preselected when the client picks nothing." }, "aiModelId": { "type": "string", "format": "uuid", "nullable": true, "description": "Catalog row id, present once anyone launched an agent on this model." } } }, "RecentModel": { "type": "object", "required": [ "slug", "name", "lastUsedAt" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "lastUsedAt": { "type": "string", "format": "date-time", "description": "Creation date of the most recent company agent using this model." } } }, "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" ] }, "Conversation": { "type": "object", "description": "One chat session between the caller and an agent. A user may hold several; see docs/specs/agent-sessions.md.", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "key": { "type": "string", "description": "Opaque engine-side key of this thread — the bare user id for the historical thread, `chat:` for every session created since. Read-only." }, "title": { "type": "string", "nullable": true, "description": "Derived from the first user message when not set explicitly." }, "meta": { "type": "object", "additionalProperties": true, "description": "Free-form per-session payload." }, "archived": { "type": "boolean" }, "unreadCount": { "type": "integer", "description": "Agent messages newer than this session's read cursor." }, "lastReadAt": { "type": "string", "format": "date-time", "nullable": true }, "lastMessageAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "key", "title", "archived", "unreadCount", "createdAt" ] }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "conversationId": { "type": "string", "format": "uuid", "description": "Session this message belongs to." }, "role": { "type": "string", "enum": [ "user", "agent" ] }, "content": { "type": "string" }, "meta": { "type": "object", "additionalProperties": true }, "flaggedAsError": { "type": "boolean", "description": "Deprecated — see `feedback`." }, "deliveryState": { "type": "string" }, "feedback": { "type": "string", "enum": [ "up", "down" ], "description": "The caller's thumbs up/down on this agent reply, if any." }, "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 }, "conversationId": { "type": "string", "format": "uuid", "description": "Chat-origin events only: the session this event belongs to. Absent on agent-wide origins (cron/subagent/system/email/webhook/interagent)." }, "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). Always null on GET /agents/{agentId}/cron-jobs (perf(projects-cron), PLAN-perf.md E3) — read it via GET /agents/{agentId}/cron-jobs/{jobId}/executions/{executionId} instead." }, "outputPreview": { "type": "string", "nullable": true, "description": "Truncated preview of execution content (max 280 chars) for list display only. Not returned on other endpoints." }, "summary": { "type": "string", "nullable": true }, "businessState": { "type": "string", "enum": [ "ok", "failed" ], "nullable": true }, "noChange": { "type": "boolean", "description": "Monitor-mode run where nothing changed (successful, no output). Never posted to the chat." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "cronJobId", "state", "startedAt" ] }, "CronExecutionOutput": { "type": "object", "description": "One execution's full output, read on demand (perf(projects-cron), PLAN-perf.md E3).", "properties": { "id": { "type": "string", "format": "uuid" }, "output": { "type": "string", "nullable": true } }, "required": [ "id", "output" ] }, "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 }, "repeatTimes": { "type": "integer", "nullable": true, "description": "Total planned runs reported by the engine; null = infinite or unknown. A success of a job with a finite count is also posted to the owner's conversation." }, "paused": { "type": "boolean", "description": "Job paused engine-side." }, "pausedReason": { "type": "string", "nullable": true }, "mode": { "type": "string", "enum": [ "agent", "monitor" ], "description": "monitor = watch job, silent while nothing changes." }, "continuity": { "type": "boolean", "description": "Session continuity between runs." }, "reasoningEffort": { "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 }, "durationMs": { "type": "integer", "nullable": true, "description": "Hermes only." }, "toolCalls": { "type": "integer", "nullable": true, "description": "Hermes only." }, "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" ] }, "companyWide": { "type": "boolean", "description": "Native platform capability (e.g. 'projects'): its connection is a company-wide singleton, resolved lazily wherever needed — never manually connected." }, "defaultGranted": { "type": "boolean", "description": "Paired with companyWide: every agent of the company holds a virtual full grant on this connection until an explicit grant row (opt-out or adjustment) exists — see IntegrationGrant.isDefault." }, "nonDeletable": { "type": "boolean", "description": "The connection can't be disconnected — DELETE /integrations/connections/{id} refuses with connection_not_deletable." }, "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" ] } } }, "isDefault": { "type": "boolean", "description": "Present (true) ONLY on a SYNTHETIC row the list endpoint fabricates for a companyWide+defaultGranted connector (e.g. 'projects') when this agent has no explicit integration_grants row yet — it already has full access by default; this row lets the UI show that instead of \"no access\". `id`/`connectionId` both equal the connection's own id on a synthetic row (no real grant row exists) — DELETE on that id persists an opt-out (a real row with allowedTools:[]) instead of a no-op. Absent (never false) on a real row." } }, "required": [ "id", "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, "description": "Company admins only — omitted for members." }, "stripeCustomerId": { "type": "string", "nullable": true, "description": "Company admins only — omitted for members." }, "stripeScheduleId": { "type": "string", "nullable": true, "description": "Company admins only — omitted for members." }, "hasStripeSubscription": { "type": "boolean", "description": "Whether a live Stripe subscription backs this row (false for a self-serve trial without card)." }, "hasStripeCustomer": { "type": "boolean", "description": "Whether the company has a Stripe customer." }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled" ] }, "currentPeriodStart": { "type": "string", "format": "date-time" }, "currentPeriodEnd": { "type": "string", "format": "date-time" }, "activeAgentsPurchased": { "type": "integer" }, "pendingActiveAgentsPurchased": { "type": "integer", "nullable": true, "description": "Target seat count of a scheduled reduction (AF-57), null when none is pending." }, "pendingReductionEffectiveAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the pending reduction lands (= currentPeriodEnd at the time it was scheduled)." }, "cancelAt": { "type": "string", "format": "date-time", "nullable": true, "description": "End-of-period cancellation scheduled on Stripe (billing portal): when the service stops. Null when none is scheduled. On a `canceled` subscription: when the service actually stopped." }, "pendingPaymentActiveAgentsPurchased": { "type": "integer", "nullable": true, "description": "A licence increase whose prorated invoice awaits payment (3DS, declined card): the seat count once paid. Null when nothing is pending." }, "pendingPaymentInvoiceUrl": { "type": "string", "nullable": true, "description": "The hosted Stripe invoice to pay for `pendingPaymentActiveAgentsPurchased`. Company admins only — omitted for members." }, "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 }, "pendingActiveAgentsPurchased": { "type": "integer", "nullable": true, "description": "Also mirrored at the top level — see CompanySubscription.pendingActiveAgentsPurchased." }, "pendingReductionEffectiveAt": { "type": "string", "format": "date-time", "nullable": true }, "trialAllowance": { "type": "object", "description": "Only when `subscription` is null: what activating the self-serve trial now would grant.", "properties": { "maxActiveAgents": { "type": "integer" }, "credits": { "type": "integer" } }, "required": [ "maxActiveAgents", "credits" ] } }, "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." }, "amountDue": { "type": "integer", "description": "Cents still due (what an open invoice shows)." }, "status": { "type": "string", "nullable": true }, "hostedInvoiceUrl": { "type": "string", "nullable": true }, "invoicePdf": { "type": "string", "nullable": true } }, "required": [ "id", "created", "amountPaid" ] }, "CustomerBillingDetails": { "type": "object", "description": "B2B invoice details held by Stripe — collected at Checkout, edited in the billing portal.", "properties": { "name": { "type": "string", "nullable": true, "description": "Legal name printed on invoices." }, "email": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true, "properties": { "line1": { "type": "string", "nullable": true }, "line2": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2." } } }, "taxIds": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Stripe tax ID type, e.g. eu_vat, gb_vat, us_ein." }, "value": { "type": "string" }, "verification": { "type": "string", "nullable": true, "enum": [ "pending", "verified", "unverified", "unavailable" ] } }, "required": [ "type", "value" ] } }, "taxLocation": { "type": "string", "nullable": true, "enum": [ "supported", "not_collecting", "unrecognized_location", "failed" ], "description": "`unrecognized_location`: Stripe Tax cannot place the customer — invoices cannot be finalized." } }, "required": [ "taxIds" ] }, "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", "enum": [ "fr", "en", "de", "es", "it", "pt-BR", "nl", "pl", "sv", "da", "tr", "ja", "ko" ], "nullable": true, "description": "Preferred UI/email locale. NULL = no preference recorded yet." }, "banned": { "type": "boolean", "description": "Not returned by GET /users/me (restricted profile)." }, "onboardingEmailsSent": { "type": "array", "items": { "type": "string" } }, "lastActiveAt": { "type": "string", "format": "date-time", "nullable": true }, "npsTriggeredAt": { "type": "string", "format": "date-time", "nullable": true }, "termsAcceptedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "First terms acceptance (signup checkbox)." }, "termsVersionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Published terms version in force at acceptance (legal_document_versions)." }, "tourSeenAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Guided tour finished or skipped. NULL = the web app opens it at next load (first login)." }, "storeyToursSeen": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" }, "description": "Storey (`dashboard` | `projects` | `floor` | `context`) → when its guided tour was finished or skipped. A missing storey = its tour opens the first time the user reaches it." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "email", "timezone" ] }, "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" ] }, "CompanyPermissions": { "type": "object", "description": "The caller's company-scoped capability matrix, computed server-side (`lib/permissions.ts`, documented in `docs/concepts/permissions.md`). Each flag says whether the UI may OFFER a gesture — it never grants one: every route keeps its own guard and answers 403 regardless. Rights that depend on the object rather than on the member are served by the object instead (`canManage` on an agent, `canArchive` on a project, `canEdit` on the org chart).", "properties": { "viewDashboard": { "type": "boolean" }, "editFloorLayout": { "type": "boolean" }, "createAgent": { "type": "boolean" }, "manageTeams": { "type": "boolean" }, "editOrgChart": { "type": "boolean" }, "viewCompanyNotices": { "type": "boolean" }, "withdrawNotices": { "type": "boolean" }, "manageIntegrationConnections": { "type": "boolean" }, "deleteWikiPage": { "type": "boolean" }, "editCompanyProfile": { "type": "boolean" }, "manageMembers": { "type": "boolean" }, "manageBilling": { "type": "boolean" }, "manageByok": { "type": "boolean" }, "manageApiKeys": { "type": "boolean" }, "viewAuditLog": { "type": "boolean" } } }, "CompanyInfo": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" }, "memberRole": { "type": "string", "enum": [ "admin", "member" ] }, "canCreateAgents": { "type": "boolean" }, "permissions": { "$ref": "#/components/schemas/CompanyPermissions" }, "byokEnabled": { "type": "boolean" }, "agentFloorEnabled": { "type": "boolean", "deprecated": true } }, "required": [ "company", "memberRole", "canCreateAgents", "permissions" ] }, "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" ] }, "FloorTeamLead": { "type": "object", "description": "The team's accountable lead, already resolved through the organisation cascade (explicit lead, else the company's root admin) and named — never the raw lead_user_id/lead_agent_id columns.", "properties": { "kind": { "type": "string", "enum": [ "human", "agent" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, "FloorTeam": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "parentId": { "type": "string", "format": "uuid", "nullable": true }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "lead": { "allOf": [ { "$ref": "#/components/schemas/FloorTeamLead" } ], "nullable": true, "description": "null only when the company has no admin at all — the one case where the cascade ends on nobody." }, "leadIsDefault": { "type": "boolean", "description": "true when the team has no lead of its own and therefore falls back on the company's root manager — the same warning the org chart shows." } }, "required": [ "id", "name", "parentId", "companyId", "lead", "leadIsDefault" ] }, "FloorAgent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed", "paused", "provisioning", "unresponsive", "failed" ] }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "avatarSeed": { "type": "string", "description": "agents.image — mascot filename in apps/web/public/aiygents." }, "createdAt": { "type": "string", "format": "date-time" }, "lastActivityAt": { "type": "string", "format": "date-time", "nullable": true, "description": "agents.lastHeartbeatAt." }, "clientId": { "type": "string", "format": "uuid", "description": "Owner — needed client-side to gate the Retry action to the owner." }, "managerHumanId": { "type": "string", "format": "uuid", "nullable": true, "description": "Unique human holder of the parent teamPositions row of this agent's own position; null when the agent holds 0 or several positions, its position is a root, or its parent is vacant/agent-held." }, "managerSource": { "type": "string", "enum": [ "own", "team", "company" ], "nullable": true, "description": "Where managerHumanId comes from: an individual override on the agent (own), its team lead or team position (team), or the company root manager as a fallback (company)." }, "engine": { "type": "string", "enum": [ "openclaw", "hermes", "opencode" ], "description": "agents.engine — same value GET /agents serves, added here so the web no longer needs a parallel GET /agents call just for the floor’s harness chip." } }, "required": [ "id", "name", "status", "teamId", "avatarSeed", "createdAt", "lastActivityAt", "clientId", "managerHumanId", "managerSource", "engine" ] }, "FloorPosition": { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid" }, "positionId": { "type": "string", "format": "uuid" }, "title": { "type": "string" } }, "required": [ "teamId", "positionId", "title" ] }, "FloorMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "type": "string", "nullable": true }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/FloorPosition" }, "description": "Every position this member holds (a member may hold several, unlike an agent)." }, "image": { "type": "string", "nullable": true, "description": "The member's own photograph (users.photo, a public Supabase Storage URL), or null when they never uploaded one — the client then draws their monogram." } }, "required": [ "id", "name", "title", "teamId", "positions", "image" ] }, "FloorLayout": { "type": "object", "description": "Stored floor arrangement (AF-41). Only what the automatic layout cannot infer: where each team platform sits, and which desk of its own team an occupant stands at. Reconciled at read time — entries whose id is no longer on the floor are stripped from the served document (never from the stored row).", "properties": { "pods": { "type": "array", "items": { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid" }, "x": { "type": "number", "description": "Pod centre, world units." }, "z": { "type": "number" } }, "required": [ "teamId", "x", "z" ] } }, "agents": { "type": "array", "description": "id = agentId, slot = desk index inside the pod of ITS OWN team (slot 0 of team A and slot 0 of team B are different desks).", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slot": { "type": "integer" } }, "required": [ "id", "slot" ] } }, "members": { "type": "array", "description": "id = userId, same slot semantics as `agents`.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slot": { "type": "integer" } }, "required": [ "id", "slot" ] } } }, "required": [ "pods", "agents", "members" ] }, "FloorState": { "type": "object", "description": "GET /floor/state — single-shot aggregated read for the Agent Floor 3D scene. Nothing stored anew: teams/positions and members come from getTeamsByCompanyId/listCompanyMembers, agents from a floor-specific minimal query.", "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/FloorTeam" } }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/FloorAgent" } }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/FloorMember" } }, "layout": { "allOf": [ { "$ref": "#/components/schemas/FloorLayout" } ], "nullable": true, "description": "null = automatic layout (nobody ever moved anything on this floor)." }, "layoutVersion": { "type": "integer", "nullable": true, "description": "Optimistic version of the stored layout; null when there is none." } }, "required": [ "teams", "agents", "members", "layout", "layoutVersion" ] }, "OrgRef": { "type": "object", "description": "A reference to a member of the organisation, whatever its nature. Humans and agents are the same kind of node in this chart.", "properties": { "kind": { "type": "string", "enum": [ "human", "agent" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "kind", "id" ] }, "OrgTeam": { "type": "object", "description": "A team as the hierarchy needs to see it.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "parentId": { "type": "string", "format": "uuid", "nullable": true }, "lead": { "allOf": [ { "$ref": "#/components/schemas/OrgRef" } ], "nullable": true, "description": "The EXPLICITLY designated lead, or null — a team with no lead falls back to the company root, and `issues` reports it as `team-lead`." } }, "required": [ "id", "name", "parentId", "lead" ] }, "OrgAgentNode": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "nullable": true, "description": "The title of the org-chart position held, when there is one." }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "manager": { "allOf": [ { "$ref": "#/components/schemas/OrgRef" } ], "nullable": true, "description": "The individual override, or null when the agent simply inherits its team's lead (the ordinary case)." } }, "required": [ "id", "name", "role", "teamId", "manager" ] }, "OrgHuman": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User id." }, "name": { "type": "string" }, "title": { "type": "string", "nullable": true }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "managerUserId": { "type": "string", "format": "uuid", "nullable": true, "description": "A person answers to a person, or to nobody — never to an agent. Null on the root of the chart." } }, "required": [ "id", "name", "title", "teamId", "managerUserId" ] }, "OrgIssue": { "type": "object", "description": "A rule the structure is currently breaking. A CODE, never a sentence: the client translates. `team-lead` — `id` is a team with no designated lead (it falls back to the root: to confirm, not to repair urgently). `agent-manager` — `id` is an agent with no manager at all. `agent-human` — `id` is an agent whose chain never reaches a person.", "properties": { "kind": { "type": "string", "enum": [ "team-lead", "agent-manager", "agent-human" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ] }, "OrgNode": { "type": "object", "description": "One box of the chart. `id` is a user, agent or team id depending on `kind` — the single exception being the VIRTUAL team `unassigned`, which has no row in the database and gathers the agents that belong to no team. `name` on that node is the literal string `unassigned`: the client names it in its own language.", "properties": { "key": { "type": "string", "description": "Stable key: `human:`, `agent:` or `team:`." }, "kind": { "type": "string", "enum": [ "human", "agent", "team" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "nullable": true }, "teamId": { "type": "string", "format": "uuid", "nullable": true, "description": "On a member node: the team it stands in. On a team node: its own id, or null for the virtual `unassigned` group." }, "memberCount": { "type": "integer", "description": "Team nodes only — agents plus humans attached to the team." }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/OrgNode" } } }, "required": [ "key", "kind", "id", "name", "role", "children" ] }, "OrgChart": { "type": "object", "description": "The whole chart, and the single payload of every /organization operation — reads AND writes. A hierarchy change moves people who were not named in the request, so a write answers with the recomputed chart rather than an acknowledgement: the client never has to make a second call, nor guess. It carries both the derived SHAPE (`tree`) and the raw CHOICES (`teams`/`agents`/`humans`, with their explicit `lead`/`manager`), which is what an editor needs to show what was decided instead of what was inferred from it.", "properties": { "rootHumanId": { "type": "string", "format": "uuid", "nullable": true, "description": "DERIVED, never stored: the oldest `admin` member. Null when the company has no admin at all — the only case where the chart has nothing to hang on." }, "tree": { "type": "object", "description": "The chart as a forest. `roots` are the people nobody stands above (normally one). `loose` collects what the structure left dangling — a team whose lead is gone stays on the chart, to be repaired rather than to vanish quietly.", "properties": { "roots": { "type": "array", "items": { "$ref": "#/components/schemas/OrgNode" } }, "loose": { "type": "array", "items": { "$ref": "#/components/schemas/OrgNode" } } }, "required": [ "roots", "loose" ] }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/OrgIssue" } }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/OrgTeam" } }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/OrgAgentNode" } }, "humans": { "type": "array", "items": { "$ref": "#/components/schemas/OrgHuman" } }, "canEdit": { "type": "boolean", "description": "True when the caller is a company admin, i.e. when the write operations below are open to them. Told here so the client never has to deduce a permission from a 403 it provoked." } }, "required": [ "rootHumanId", "tree", "issues", "teams", "agents", "humans", "canEdit" ] }, "OrgCandidate": { "type": "object", "description": "Someone an editor may propose as a manager or a team lead. Impossible candidates are listed too, carrying the reason they are blocked — \"why is that one greyed out\" is a question about the model, and the choice list is where the model must answer it.", "properties": { "ref": { "$ref": "#/components/schemas/OrgRef" }, "name": { "type": "string" }, "role": { "type": "string" }, "blockedReason": { "type": "string", "nullable": true, "enum": [ "SELF", "CYCLE", "NO_HUMAN_MANAGER", "HUMAN_NEEDS_HUMAN" ], "description": "Null when the candidate can be chosen. A stable CODE, never a sentence: the client translates it." } }, "required": [ "ref", "name", "role", "blockedReason" ] }, "ProjectTone": { "type": "string", "enum": [ "amber", "mint", "periwinkle", "plum", "blush" ] }, "ProjectStatus": { "type": "string", "enum": [ "active", "paused", "done" ] }, "ProjectColumnKind": { "type": "string", "enum": [ "backlog", "active", "review", "done" ] }, "ProjectStarter": { "type": "object", "description": "The labels a brand-new project starts with, written by the caller in the user's own language: the wiki home page and the board's first columns. Omit it entirely and the API writes its own French defaults (Backlog / À faire / En cours / Revue / Terminé, page « Overview ») — it holds no translations of its own. All-or-nothing on `wikiTitle` and `columns`: a starter carrying only the columns would leave the wiki in the other language. `kind` — not the translated name — stays the stable marker for \"done\".", "required": [ "wikiTitle", "columns" ], "properties": { "wikiTitle": { "type": "string", "minLength": 1, "maxLength": 200 }, "wikiContent": { "type": "string", "maxLength": 20000, "description": "Markdown body of the home page. Defaults to a skeleton built from the project name." }, "wikiMessage": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Message of the page's first revision. Defaults to « Création du wiki »." }, "columns": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "$ref": "#/components/schemas/ProjectColumnKind" } } } } } }, "ProjectParticipant": { "type": "object", "description": "Somebody on the project — a human or an agent, both held the same way so a card can be assigned to either. `id` is the project_members row id (that is what a card's `assignee` points at), NOT the user/agent id. `kind` is derived from the row (agent_id set ⇒ agent), never stored.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "description": "Free text shown on the card (\"Chef de projet\"…) — unrelated to platform permissions." }, "kind": { "type": "string", "enum": [ "human", "agent" ] }, "memberRef": { "type": "string", "format": "uuid", "description": "The user id (human) or agent id — stable across projects, unlike `id`." }, "photo": { "type": "string", "nullable": true, "description": "The person's own profile picture (`users.photo`), null when they have not uploaded one — and always null for an agent, which has no face. Never a stand-in: a participant without a photo is shown by their initials." } }, "required": [ "id", "name", "role", "kind", "photo" ] }, "ProjectColumn": { "type": "object", "description": "One column of a project's board. Columns belong to the project — Atako imposes no global set of states — so `kind` is how the rest of the interface knows which column means finished without hard-coding a name.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ProjectColumnKind" } }, "required": [ "id", "name", "kind" ] }, "ProjectSummary": { "type": "object", "description": "One row of GET /projects — aggregate counts computed in SQL plus a short participant list for the avatar stack. Carries no cards.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "tone": { "$ref": "#/components/schemas/ProjectTone" }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "space": { "type": "string", "nullable": true, "maxLength": 60, "description": "Free-form label grouping projects (e.g. \"Marketing\"); one per project, exact-match grouping; null = no space." }, "owner": { "type": "string", "description": "Display name of whoever opened the project; \"\" once that user is gone." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "counts": { "type": "object", "properties": { "cards": { "type": "object", "description": "`done` counts cards standing in the column whose `kind` is `done` (never a column name); `blocked` counts cards carrying a blocking reason. Archived cards are excluded.", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "blocked": { "type": "integer" } }, "required": [ "total", "done", "blocked" ] }, "members": { "type": "integer" }, "wikiPages": { "type": "integer" } }, "required": [ "cards", "members", "wikiPages" ] }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectParticipant" } } }, "required": [ "id", "name", "description", "tone", "status", "space", "owner", "createdAt", "updatedAt", "archivedAt", "counts", "participants" ] }, "Project": { "type": "object", "description": "A project and everything on it, in one read. A card has no status — its state IS the column it stands in — and the wiki is a tree of pages, each carrying snapshots of its own past.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "tone": { "$ref": "#/components/schemas/ProjectTone" }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "space": { "type": "string", "nullable": true, "maxLength": 60, "description": "Free-form label grouping projects (e.g. \"Marketing\"); one per project, exact-match grouping; null = no space." }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectParticipant" } }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectColumn" }, "description": "Ordered by position." }, "cards": { "type": "array", "description": "Non-archived cards, ordered by column then position, each with its labels, checklist and comments. The embedded comments carry no `id` here (only author/at/text) — the comment operations return the full ProjectCardComment.", "items": { "$ref": "#/components/schemas/ProjectCard" } }, "wiki": { "type": "array", "description": "Root pages of the wiki, each carrying its own `children` subtree and its `history` (newest revision first).", "items": { "$ref": "#/components/schemas/ProjectWikiPage" } } }, "required": [ "id", "name", "description", "tone", "status", "space", "owner", "createdAt", "updatedAt", "archivedAt", "participants", "columns", "cards", "wiki" ] }, "ProjectCardPriority": { "type": "string", "enum": [ "low", "normal", "high" ] }, "ProjectCardChecklistItem": { "type": "object", "description": "One line of a card's checklist — the small steps a card is made of, ticked off without splitting it into more cards.", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "done": { "type": "boolean" } }, "required": [ "text", "done" ] }, "ProjectCardComment": { "type": "object", "description": "A message on a card — where the discussion that led to a decision stays attached to the work it decided. `author` is the display name frozen when the comment was written, so someone leaving the company never empties the thread behind them. `id` is present on everything the card operations return; the copy embedded in GET /projects/{id} carries only author/at/text.", "properties": { "id": { "type": "string", "format": "uuid" }, "author": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "text": { "type": "string", "maxLength": 10000 } }, "required": [ "author", "at", "text" ] }, "ProjectCard": { "type": "object", "description": "A unit of work on the board. It carries no status field: where the card stands IS its state, so read `column`. `blocked` and `due` are absent rather than null when unset — asking whether a card is blocked is asking for the reason.", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "maxLength": 20000 }, "assignee": { "type": "string", "format": "uuid", "nullable": true, "description": "A ProjectParticipant id (project_members row) — human or agent, both assignable — or null when nobody has taken the card." }, "column": { "type": "string", "format": "uuid", "description": "The column the card stands in: its state." }, "priority": { "$ref": "#/components/schemas/ProjectCardPriority" }, "blocked": { "type": "string", "maxLength": 500, "description": "Why the card cannot move. Absent when it is not blocked — there is no blocked flag, only the reason." }, "labels": { "type": "array", "items": { "type": "string", "maxLength": 40 } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "due": { "type": "string", "format": "date-time", "description": "Absent when the card has no deadline." }, "checklist": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectCardChecklistItem" } }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectCardComment" }, "description": "Oldest first — a discussion is read in the order it was written, not like an inbox." } }, "required": [ "id", "title", "description", "assignee", "column", "priority", "labels", "createdAt", "updatedAt", "checklist", "comments" ] }, "ProjectColumnOrder": { "type": "object", "description": "The up-to-date contents of one column, so a board can be redrawn after a move without reloading the project. Only the columns the move actually touched are reported — one when the card stayed in place, two when it changed column.", "properties": { "id": { "type": "string", "format": "uuid" }, "cardIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Live cards, top to bottom. Archived cards are never listed." } }, "required": [ "id", "cardIds" ] }, "ProjectWikiRevision": { "type": "object", "description": "One past state of a page, kept whole rather than as a patch, so reading an old version costs a single read. `sha` is a 7-character fingerprint unique within the page, and `author` is frozen at write time like a card comment's.", "properties": { "id": { "type": "string", "format": "uuid" }, "sha": { "type": "string", "description": "Short content fingerprint, as Git displays one." }, "at": { "type": "string", "format": "date-time" }, "author": { "type": "string" }, "message": { "type": "string", "maxLength": 500, "description": "Why the page was written, in the spirit of a commit message." }, "content": { "type": "string", "description": "The page's full Markdown at that moment." } }, "required": [ "id", "sha", "at", "author", "message", "content" ] }, "ProjectWikiRevisionSummary": { "type": "object", "description": "A revision's metadata, without its text (perf(projects-cron), PLAN-perf.md E3) — what GET /projects/{id} embeds for every page's history, since that single read already returns the whole project and every revision's full Markdown on top of that made it arbitrarily large. `size` is the text's length in characters, computed in SQL so it never travels over the wire; the text itself is a separate, on-demand read (GET /projects/{id}/wiki/{pageId}/revisions/{revisionId}).", "properties": { "id": { "type": "string", "format": "uuid" }, "sha": { "type": "string", "description": "Short content fingerprint, as Git displays one." }, "at": { "type": "string", "format": "date-time" }, "author": { "type": "string" }, "message": { "type": "string", "maxLength": 500, "description": "Why the page was written, in the spirit of a commit message." }, "size": { "type": "integer", "description": "Length of this revision's content, in characters." } }, "required": [ "id", "sha", "at", "author", "message", "size" ] }, "ProjectWikiRevisionContent": { "type": "object", "description": "One revision's full text, read on demand (perf(projects-cron), PLAN-perf.md E3).", "properties": { "id": { "type": "string", "format": "uuid" }, "content": { "type": "string", "description": "The page's full Markdown at that moment." } }, "required": [ "id", "content" ] }, "ProjectWikiNode": { "type": "object", "description": "An entry of the wiki's table of contents: where a page sits, not what it says. `content` appears only when the caller asked for it (`?withContent=true`), and `revisionCount` lets the sidebar show how often a page was rewritten without loading any history.", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 200 }, "path": { "type": "string", "maxLength": 500 }, "position": { "type": "integer", "description": "Rank among its siblings." }, "revisionCount": { "type": "integer" }, "content": { "type": "string" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectWikiNode" } } }, "required": [ "id", "title", "path", "position", "revisionCount", "children" ] }, "ProjectWikiPageDetail": { "type": "object", "description": "An open page: its current text, a page of its history (newest first) and its sub-pages as table-of-contents entries. Every wiki write returns this same shape, so an editor never has to re-read the page it just saved.", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 200 }, "path": { "type": "string", "maxLength": 500 }, "position": { "type": "integer" }, "parentId": { "type": "string", "format": "uuid", "nullable": true, "description": "null for a page sitting at the root of the wiki." }, "content": { "type": "string", "description": "Always identical to `history[0].content` — the two are written in the same transaction and cannot diverge." }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectWikiRevision" }, "description": "Newest first, capped by `limit` (50 by default)." }, "historyTotal": { "type": "integer", "description": "Revisions the page has in all, beyond the slice returned." }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectWikiNode" } } }, "required": [ "id", "title", "path", "position", "parentId", "content", "history", "historyTotal", "children" ] }, "ProjectWikiPage": { "type": "object", "description": "A wiki page the way GET /projects/{id} embeds it — the whole tree in one read, every page with its current text and the SUMMARY of its history (metadata only, no revision text — perf(projects-cron), PLAN-perf.md E3). The wiki operations return the richer ProjectWikiPageDetail instead, whose `history` still carries each revision's full text.", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "path": { "type": "string" }, "content": { "type": "string" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectWikiRevisionSummary" }, "description": "Newest first." }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectWikiPage" } } }, "required": [ "id", "title", "path", "content", "history", "children" ] }, "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" }, "scope": { "type": "string", "enum": [ "read", "write" ], "description": "`read`: GET only. `write`: everything except the operations marked `x-atako-api-key: forbidden`." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Past this instant the key is refused (401 API_KEY_EXPIRED). Null = never." }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "keyPrefix", "active", "scope", "expiresAt", "createdAt" ] }, "ApiKeyListed": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" } ], "type": "object", "description": "A key of GET /users/api-keys, with the member who created it.", "properties": { "owner": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] } }, "required": [ "owner" ] }, "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" ] }, "AuditLogActor": { "description": "Who performed the action — a member, an agent acting on the company's behalf, or the system itself.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } }, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true } }, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind" ] } ] }, "AuditLogEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "denied", "error" ] }, "entityType": { "type": "string", "nullable": true }, "entityId": { "type": "string", "nullable": true }, "ip": { "type": "string", "nullable": true }, "meta": { "type": "object", "nullable": true, "additionalProperties": true }, "actor": { "$ref": "#/components/schemas/AuditLogActor" }, "target": { "type": "object", "nullable": true, "description": "Who/what the action was about, when that differs from the actor (e.g. a member removed by an admin).", "properties": { "userId": { "type": "string", "format": "uuid" }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true } }, "required": [ "userId" ] } }, "required": [ "id", "createdAt", "action", "status", "actor" ] }, "AuditLogPage": { "type": "object", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor — pass back as `?cursor=` to fetch the next page, null once exhausted." } }, "required": [ "logs", "nextCursor" ] }, "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" ] }, "RoadmapEntry": { "type": "object", "description": "Une entrée de la roadmap produit. `shippedAt` n'est renseignée que pour `status: shipped`.", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "storey": { "type": "string", "enum": [ "dashboard", "projects", "floor", "context", "settings", "global" ] }, "status": { "type": "string", "enum": [ "planned", "in_progress", "shipped" ] }, "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" } }, "position": { "type": "integer", "description": "Rang d'affichage ; à égalité, `createdAt` départage." }, "shippedAt": { "type": "string", "format": "date-time", "nullable": true }, "publishedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "slug", "storey", "status", "title", "description", "position" ] }, "ChangelogEntry": { "type": "object", "description": "Une livraison. `releasedAt` est la date de la LIVRAISON — c'est elle qui trie — distincte de `publishedAt`, qui ne dit que la visibilité de la fiche.", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "version": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "added", "improved", "fixed" ] }, "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" } }, "body": { "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" } }, "releasedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "slug", "kind", "title", "body", "releasedAt" ] }, "PressRelease": { "type": "object", "description": "Un communiqué de presse. `location` est le lieu de la ligne d'en-tête (« Paris, le… ») ; la date est `publishedAt`.", "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" } }, "location": { "type": "string", "nullable": true }, "contactEmail": { "type": "string", "nullable": true }, "mediaKitUrl": { "type": "string", "nullable": true }, "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" ] }, "SiteBanner": { "type": "object", "description": "La bande posée tout en haut de la fenêtre. Seules celles À L'ANTENNE sortent d'ici : ni brouillon, ni prévue, ni passée — `startsAt`/`endsAt` sont donc informatives, pas un filtre à appliquer côté client. Un `linkUrl` sans `linkLabel` veut dire que le MESSAGE ENTIER est le lien.", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "marketing", "technical" ], "description": "Décide du ton visuel, et rien d'autre." }, "audience": { "type": "string", "enum": [ "marketing", "app", "both" ] }, "icon": { "type": "string", "nullable": true, "description": "Nom d'icône pris dans une liste fermée (`Megaphone`, `Sparkles`, `Gift`, `Rocket`, `Info`, `TriangleAlert`, `OctagonAlert`, `Wrench`, `Clock`)." }, "message": { "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" } }, "linkUrl": { "type": "string", "nullable": true }, "linkLabel": { "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" }, "nullable": true }, "buttonLabel": { "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" }, "nullable": true }, "buttonUrl": { "type": "string", "nullable": true }, "dismissible": { "type": "boolean" }, "startsAt": { "type": "string", "format": "date-time", "nullable": true }, "endsAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Borne EXCLUSIVE." }, "publishedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "audience", "message", "dismissible" ] }, "NoticeOption": { "type": "object", "description": "One answer button, frozen on the notice when it was raised. Canonical ids (`always`, `once`, `deny`, `unblocked`, `dropped`, `seen`, `other`) are translated by the client; `c0`…`cn` ids carry the agent's own wording in `label` and must be shown as-is.", "properties": { "id": { "type": "string", "description": "Answer id — what you send back in `POST /notices/{id}/respond`." }, "label": { "type": "string" }, "tone": { "type": "string", "enum": [ "ok", "warn", "bad", "quiet" ], "description": "Suggested button colour." }, "free": { "type": "boolean", "description": "When true, this option opens a free-text field and `text` becomes required on respond." } }, "required": [ "id", "label" ] }, "NoticeAnswer": { "type": "object", "description": "The human decision, once made. `respondedByName` is frozen at answer time so the decision stays readable after the account is gone.", "properties": { "chosenOption": { "type": "string", "nullable": true }, "freeText": { "type": "string", "nullable": true }, "respondedBy": { "type": "string", "format": "uuid", "nullable": true }, "respondedByName": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "chosenOption", "createdAt" ] }, "NoticeOrigin": { "type": "object", "description": "Where the question came from — the work object that raised it. Declared by the agent when it raises the notice, never guessed server-side. `null` on a notice raised before origins existed.", "properties": { "kind": { "type": "string", "enum": [ "chat", "cron", "email", "webhook", "interagent", "subagent" ] }, "conversationId": { "type": "string", "format": "uuid", "nullable": true, "description": "The chat session, for `chat` origins only. This is what the session deep link carries." }, "refId": { "type": "string", "nullable": true, "description": "The object id for the five other kinds: email threadId, webhook endpointId, interagent contextId, cronJobId, subAgentId." }, "label": { "type": "string", "nullable": true, "description": "Human-readable name of that object (session title, thread subject, job title). `null` when it has none or has since been deleted — the link still works, it just shows the kind." } }, "required": [ "kind", "conversationId", "refId", "label" ] }, "Notice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "agentName": { "type": "string" }, "recipientUserId": { "type": "string", "format": "uuid" }, "recipientName": { "type": "string" }, "kind": { "type": "string", "enum": [ "blocker", "guardrail", "choice", "info" ], "description": "Blocked / permission asked / arbitration / information. The first three are blocking: the agent waits." }, "priority": { "type": "string", "enum": [ "critical", "high", "normal", "low" ] }, "subject": { "type": "string", "description": "Short, stable — the deduplication key is derived from it, together with the origin: the same subject raised from two different sessions is two questions." }, "question": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/NoticeOption" } }, "state": { "type": "string", "enum": [ "open", "answered", "expired", "withdrawn" ] }, "createdAt": { "type": "string", "format": "date-time" }, "answeredAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "settledAt": { "type": "string", "format": "date-time", "description": "`answeredAt` if answered, else `createdAt` — always set, including on an open notice. The one reliable date to show on a settled notice with no answer (`expired`/`withdrawn`)." }, "origin": { "$ref": "#/components/schemas/NoticeOrigin", "nullable": true }, "answer": { "$ref": "#/components/schemas/NoticeAnswer", "nullable": true } }, "required": [ "id", "agentId", "agentName", "recipientUserId", "kind", "priority", "subject", "question", "options", "state", "createdAt", "settledAt" ] }, "NoticeList": { "type": "object", "description": "`nextCursor` is only meaningful on the history sort (a settled `state`, `all`, or `order=recent`) — pass it back as `?cursor=` for the next page. It is always `null` on the default open queue (AF-52): that sort is a plain `limit`, never paginated.", "properties": { "notices": { "type": "array", "items": { "$ref": "#/components/schemas/Notice" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next history page, null once exhausted (or not applicable)." } }, "required": [ "notices", "nextCursor" ] }, "NoticeCount": { "type": "object", "description": "Badge counters. `blocking` is a SUBSET of `open` (everything but `info`), never a separate total.", "properties": { "open": { "type": "integer" }, "blocking": { "type": "integer" } }, "required": [ "open", "blocking" ] }, "RespondNoticeRequest": { "type": "object", "properties": { "option": { "type": "string", "description": "The `id` of one of the notice's `options`." }, "text": { "type": "string", "description": "Required and non-empty when the chosen option has `free: true`; ignored otherwise." } }, "required": [ "option" ] }, "Notification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "agent", "payment", "message", "invoice", "system", "review" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "titleKey": { "type": "string", "nullable": true }, "bodyKey": { "type": "string", "nullable": true }, "params": { "type": "object", "nullable": true, "additionalProperties": true }, "read": { "type": "boolean" }, "href": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "title", "body", "read", "timestamp" ] }, "AgentSharedItem": { "type": "object", "description": "A document or secret shared with an agent. `value` is only returned by the detail and create endpoints.", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "uploadedBy": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "document", "secret" ] }, "name": { "type": "string" }, "mimeType": { "type": "string", "nullable": true }, "fileSize": { "type": "integer", "nullable": true }, "value": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "type", "name", "createdAt" ] }, "AgentEmailSettings": { "type": "object", "properties": { "address": { "type": "string" }, "enabled": { "type": "boolean" }, "senderPolicy": { "type": "string", "enum": [ "open", "allowlist" ] }, "coldSendMode": { "type": "string", "enum": [ "approval", "auto", "disabled" ] }, "allowlist": { "type": "array", "items": { "type": "string" } }, "denylist": { "type": "array", "items": { "type": "string" } }, "dailySendQuota": { "type": "integer", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "pendingApprovalCount": { "type": "integer" } }, "required": [ "address", "enabled", "senderPolicy", "coldSendMode", "allowlist", "denylist" ] }, "AgentEmailThread": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalEmail": { "type": "string" }, "participants": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "status": { "type": "string" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "lastDirection": { "type": "string", "enum": [ "inbound", "outbound" ] }, "unread": { "type": "boolean" }, "messageCount": { "type": "integer" }, "lastSnippet": { "type": "string" } }, "required": [ "id", "subject", "lastMessageAt" ] }, "AgentEmailMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "fromEmail": { "type": "string" }, "toEmails": { "type": "array", "items": { "type": "string" } }, "ccEmails": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "textBody": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size": { "type": "integer" }, "contentType": { "type": "string" }, "url": { "type": "string", "nullable": true } } } }, "deliveryState": { "type": "string", "nullable": true }, "outboundStatus": { "type": "string", "nullable": true, "description": "pending_approval | queued | sent | bounced | failed | suppressed | rejected (outbound only)." }, "isAutoReply": { "type": "boolean" }, "isColdSend": { "type": "boolean", "nullable": true }, "isInternalSend": { "type": "boolean", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "direction", "createdAt" ] }, "WebhookFilter": { "type": "object", "properties": { "field": { "type": "string", "maxLength": 200 }, "op": { "type": "string", "enum": [ "eq", "neq", "in", "exists", "contains" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "field", "op" ] }, "AgentWebhookEndpoint": { "type": "object", "description": "Never carries the full URL token nor the verification secret.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "provider": { "type": "string", "enum": [ "none", "shared_secret", "hmac_generic", "standard_webhooks", "stripe", "github", "custom" ] }, "tokenPrefix": { "type": "string" }, "hasVerificationSecret": { "type": "boolean" }, "signatureConfig": { "type": "object", "nullable": true, "additionalProperties": true }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookFilter" } }, "maxPayloadBytes": { "type": "integer", "nullable": true }, "rateLimitPerMinute": { "type": "integer", "nullable": true }, "dailyTurnQuota": { "type": "integer", "nullable": true }, "totalEventsCount": { "type": "integer" }, "rejectedRequestsCount": { "type": "integer" }, "lastRejectedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastRejectedCode": { "type": "integer", "nullable": true }, "lastEventAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "status", "provider", "tokenPrefix" ] }, "AgentWebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_agent", "delivered", "skipped", "quarantined" ] }, "reasonCode": { "type": "string", "nullable": true }, "providerEventId": { "type": "string", "nullable": true }, "duplicateDeliveryCount": { "type": "integer" }, "payloadTruncated": { "type": "boolean" }, "isTest": { "type": "boolean" }, "deliveredToAgentAt": { "type": "string", "format": "date-time", "nullable": true }, "turnId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "createdAt" ] }, "LlmProviderKey": { "type": "object", "description": "A company bring-your-own-key inference key. The secret is never returned.", "properties": { "id": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "openrouter", "openai", "anthropic" ] }, "label": { "type": "string" }, "config": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "pending_validation", "active", "invalid", "disabled" ] }, "priority": { "type": "integer" }, "isDefaultForCompany": { "type": "boolean" }, "monthlyCapUsd": { "type": "number", "nullable": true }, "lastValidatedAt": { "type": "string", "format": "date-time", "nullable": true }, "discoveredModels": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "activeAgentCount": { "type": "integer" } }, "required": [ "id", "provider", "label", "status" ] } } }, "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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "createAgent", "summary": "Create an agent", "description": "Requires an active subscription and `canCreateAgents` permission. `teamId` may be ANY team of your live company; a team outside it (or belonging to no company) is only accepted if you belong to it — NOT_TEAM_MEMBER (403) otherwise. Guards, checked in order: NOT_TEAM_MEMBER (403), 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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/agents/{id}/cancel": { "post": { "operationId": "cancelAgent", "summary": "Cancel a provisioning agent", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404.", "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" }, "name": { "type": "string", "description": "The cancelled agent's name — rides along for the caller's audit-log entry." } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown agent, or the caller is neither its owner nor an admin of the owner's company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_CANCELLABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{id}/retry-provisioning": { "post": { "operationId": "retryAgentProvisioning", "summary": "Retry a failed provisioning", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404. 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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_ACTIVE_SUBSCRIPTION", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown agent, or the caller is neither its owner nor an admin of the owner's company.", "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": [] } ], "x-atako-api-key": "write" } }, "/agents/{id}/end": { "post": { "operationId": "endAgent", "summary": "End an active agent", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404.", "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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown agent, or the caller is neither its owner nor an admin of the owner's company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_ACTIVE — agent already ended; or `code: AGENT_PROVISIONING` — still provisioning, cancel it instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/agents/{id}/export": { "get": { "operationId": "exportAgent", "summary": "Export everything an agent holds, as a JSON attachment", "description": "Conversations, messages, e-mail threads and scheduled tasks. The way out for a company that will not subscribe before the trial-end retention window closes on a cascade delete (docs/specs/trial-end-lifecycle.md). Requires the same administration rights as renaming or ending the 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": { "exportedAt": { "type": "string", "format": "date-time" }, "agent": { "type": "object" }, "conversations": { "type": "array", "items": { "type": "object" } }, "emailThreads": { "type": "array", "items": { "type": "object" } }, "scheduledTasks": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/agents/{id}/upgrade": { "post": { "operationId": "upgradeAgent", "summary": "Trigger an in-place engine image upgrade", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404. 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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown agent, or the caller is neither its owner nor an admin of the owner's company.", "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": [] } ], "x-atako-api-key": "write" } }, "/agents/{id}/name": { "patch": { "operationId": "renameAgent", "summary": "Set the agent's display name", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404.", "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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown agent, or the caller is neither its owner nor an admin of the owner's company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{id}/role": { "patch": { "operationId": "setAgentRole", "summary": "Set or clear the agent's job title", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404. `role: null` (or a blank string) CLEARS the title — a titleless agent is a normal state, not an error. The org chart the agent reads every turn uses `team_positions.title` first and falls back to this. Nothing is pushed: the change reaches the agent on its next turn.", "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": [ "role" ], "properties": { "role": { "type": "string", "maxLength": 120, "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "nullable": true } } } } } }, "400": { "description": "role must be a string or null / role must be at most 120 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown agent, or the caller is neither its owner nor an admin of the owner's company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{id}/instructions": { "patch": { "operationId": "setAgentInstructions", "summary": "Edit the agent's mission, instructions and business context", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404. Each field is optional: absent = unchanged, `null` or blank = cleared, otherwise trimmed (≤ 20 000 characters). At least one field is required. Nothing is pushed: the agent re-reads its profile every turn.", "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", "properties": { "mission": { "type": "string", "nullable": true, "maxLength": 20000 }, "instructions": { "type": "string", "nullable": true, "maxLength": 20000 }, "businessContext": { "type": "string", "nullable": true, "maxLength": 20000 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "mission": { "type": "string", "nullable": true }, "instructions": { "type": "string", "nullable": true }, "businessContext": { "type": "string", "nullable": true } } } } } }, "400": { "description": "invalid body / must be a string or null / must be at most 20000 characters / at least one field is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown agent, or the caller is neither its owner nor an admin of the owner's company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{id}/team": { "patch": { "operationId": "setAgentTeam", "summary": "Move the agent to a team, or make it personal", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404. The target team may be ANY team of the agent owner's live company. A team outside it (or a team belonging to no company) is only accepted if the CALLER belongs to it — NOT_TEAM_MEMBER otherwise.", "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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "NOT_TEAM_MEMBER", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found (or not yours to administer), or teamId does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{id}/model": { "patch": { "operationId": "setAgentModel", "summary": "Change the LLM model of a live agent", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404. `modelId` is an `ai_models` UUID or an OpenRouter slug (same shapes as at creation). Takes effect on the agent's next LLM call. A free OpenRouter model is refused (400) on Atako inference; a direct-provider (OpenAI/Anthropic) BYOK agent and an ended/failed agent answer 409.", "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": [ "modelId" ], "properties": { "modelId": { "type": "string" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string", "format": "uuid" }, "model": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "contextLength": { "type": "integer", "nullable": true } } } } } } } }, "400": { "description": "modelId must be a non-empty string / Model not found / MODEL_NOT_AVAILABLE_ON_ATAKO_INFERENCE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown agent, or the caller is neither its owner nor an admin of the owner's company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "DIRECT_PROVIDER_MODEL_IMMUTABLE / AGENT_NOT_ACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{id}/llm-key": { "patch": { "operationId": "setAgentLlmKey", "summary": "Reassign the agent's BYOK LLM key", "description": "Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404. The key must belong to the AGENT's company, so this never reaches another user's personal 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, or revoked session (SESSION_REVOKED).", "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": "Unknown agent, or the caller is neither its owner nor an admin of the owner's company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/conversations": { "get": { "operationId": "listConversations", "summary": "List the caller's chat sessions with an agent", "description": "Most recently active first. Archived sessions are excluded unless `includeArchived=true`.", "tags": [ "Messages" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "required": false, "description": "Include archived sessions.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "createConversation", "summary": "Open a new chat session with an agent", "description": "The session gets its own engine-side key (`chat:`), so its context is isolated from every other session of the same agent.", "tags": [ "Messages" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200, "nullable": true }, "meta": { "type": "object", "additionalProperties": true, "nullable": true } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/conversations/{id}": { "get": { "operationId": "getConversation", "summary": "One chat session", "tags": [ "Messages" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "patch": { "operationId": "updateConversation", "summary": "Rename, archive or un-archive a chat session", "tags": [ "Messages" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200, "nullable": true }, "archived": { "type": "boolean" }, "meta": { "type": "object", "additionalProperties": true, "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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" } }, { "name": "conversationId", "in": "query", "required": false, "description": "Session to read/write. Omitted = the caller's most recently active session (created on demand) — what every client written before sessions existed gets. A session that is not the caller's own on this agent answers 404.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "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" }, "conversationId": { "type": "string", "format": "uuid", "description": "Session to read/write. Omitted = the caller's most recently active session (created on demand) — what every client written before sessions existed gets. A session that is not the caller's own on this agent answers 404." } } } } } }, "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, or revoked session (SESSION_REVOKED).", "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_MESSAGEABLE — the agent is ended, failed or paused (resume it first); `status` carries its current status. A provisioning or unresponsive agent accepts messages and gets them once connected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/turns/steer": { "post": { "operationId": "steerAgentTurn", "summary": "Add an instruction to the agent's running turn", "description": "Hermes agents only. The instruction is queued and delivered after the current tool batch, and kept in the session history as a user message with `meta.kind = steer` (never delivered again as a chat message). 202: the frame was sent; the outcome arrives over SSE `turn_control_result` (`ok`, or `code`: no_active_turn | too_late | unsupported_engine | error). Designate the session with `conversationId` or `conversationKey` (omit both: default session).", "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": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 4000 }, "conversationId": { "type": "string", "format": "uuid" }, "conversationKey": { "type": "string" } } } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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_CONNECTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/turns/stop": { "post": { "operationId": "stopAgentTurn", "summary": "Stop the agent's running turn", "description": "Hermes agents only. Hard stop: the partial answer (if any) is posted with `meta.interrupted`. 202: the frame was sent; the outcome arrives over SSE `turn_control_result`.", "tags": [ "Messages" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid" }, "conversationKey": { "type": "string" } } } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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_CONNECTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/messages/{messageId}/flag": { "post": { "operationId": "flagMessage", "summary": "Flag a message as an error (deprecated — recorded as a thumbs down, use PUT …/feedback)", "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/messages/{messageId}/feedback": { "put": { "operationId": "setMessageFeedback", "summary": "Thumbs up / down an agent reply (replaces any previous verdict)", "description": "Only on role `agent` messages of one of your own sessions. Any change sends the feedback back to the support 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": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rating" ], "properties": { "rating": { "type": "string", "enum": [ "up", "down" ] }, "note": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Optional free text." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": [ "up", "down" ] }, "note": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Invalid body, or NOT_AGENT_MESSAGE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "clearMessageFeedback", "summary": "Remove your thumbs up / down from an agent reply (idempotent)", "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" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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" } }, { "name": "conversationId", "in": "query", "required": false, "description": "Narrows the feed to ONE session of the caller on this agent (404 otherwise). Omitted = agent-wide, as before sessions existed.", "schema": { "type": "string", "format": "uuid" } } ], "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/models/catalog": { "get": { "operationId": "listModelCatalog", "summary": "List the whole OpenRouter catalog with Atako flags", "description": "Every model reachable through the platform gateway (~400), flat and sorted by provider label then name, served from a 10-minute memory cache. `suggested` only marks the models Atako recommends (`GET /models`); all the others are just as selectable when creating an agent. Prices are $/token.", "tags": [ "Agent Options" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogModel" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "OpenRouter is unreachable and nothing is cached yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/models/recent": { "get": { "operationId": "listRecentModels", "summary": "Models the caller's company already launched agents on", "description": "Deduplicated by slug, most recently used first, at most 8. Derived from the company agents; BYOK direct-provider agents are excluded.", "tags": [ "Agent Options" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecentModel" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/models/favorites": { "get": { "operationId": "listFavoriteModels", "summary": "List the starred model slugs (company-wide)", "tags": [ "Agent Options" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "example": "anthropic/claude-sonnet-4" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "put": { "operationId": "setFavoriteModel", "summary": "Star or unstar one model for the whole company", "description": "Idempotent both ways. Starring rejects a slug absent from the OpenRouter catalog; unstarring never validates, so a model that left the catalog stays removable. Returns the up-to-date list.", "tags": [ "Agent Options" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "favorite" ], "properties": { "slug": { "type": "string", "description": "OpenRouter model slug, from GET /models/catalog." }, "favorite": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Missing `slug`/`favorite`, or a slug unknown to the OpenRouter catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/agent-engines": { "get": { "operationId": "listAgentEngines", "summary": "List runtime engines and the default used when creating an agent", "description": "Distinct from `/harnesses` (an optional, backoffice-managed catalog): the engine is what actually runs the agent, and a new agent always falls back to `default` when `engine` is omitted on creation.", "tags": [ "Agent Options" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "engines", "default" ], "properties": { "engines": { "type": "array", "items": { "type": "string" }, "example": [ "openclaw", "hermes", "opencode" ] }, "default": { "type": "string", "example": "hermes" }, "profiles": { "type": "array", "description": "Capability profile per engine — what the API will actually allow (channels, integrations, interagent mode, repo requirement), plus `selectable`: whether it may still be picked when creating an agent (an unselectable engine stays valid for agents already running on it).", "items": { "type": "object", "required": [ "engine", "selectable", "channels", "integrations", "interagent", "requiresRepos", "capabilities" ], "properties": { "engine": { "type": "string", "example": "opencode" }, "selectable": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "chat", "email", "webhook", "interagent", "cron" ] } }, "integrations": { "description": "`'all'`, or the provider keys this engine may be granted.", "oneOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string" } } ] }, "interagent": { "type": "string", "enum": [ "full", "receive_only" ] }, "requiresRepos": { "type": "boolean" }, "capabilities": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/users/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List the company's programmatic API keys", "description": "Company-admin only, signed-in session only: an API key gets `403 API_KEY_FORBIDDEN`. Every key created by a member of the caller's company, with its creator. A key stops authenticating as soon as its creator is no longer a company admin (keys are revoked on demotion or removal).", "tags": [ "API Keys" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyListed" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" }, "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 }, "scope": { "type": "string", "enum": [ "read", "write" ], "default": "write" }, "expiresInDays": { "type": "integer", "enum": [ 30, 90, 365 ], "nullable": true, "description": "Null or omitted = never expires." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" } } } }, "400": { "description": "name required / invalid scope / invalid expiresInDays", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/users/api-keys/{id}": { "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "description": "Company-admin only. Any key of the caller's company, not only the caller's own.", "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/users/api-keys/{id}/permanent": { "delete": { "operationId": "deleteApiKeyPermanently", "summary": "Permanently delete an already-revoked API key", "description": "Company-admin only. The key must be revoked first (`DELETE /users/api-keys/{id}`) — deleting an active key is refused.", "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, or revoked session (SESSION_REVOKED).", "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" } } } }, "409": { "description": "Revoke the key before deleting it — the key is still active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "forbidden" } }, "/company/audit-log": { "get": { "operationId": "listCompanyAuditLog", "summary": "List the company audit journal", "description": "Company-admin only. Cursor-paginated, most recent first by default.", "tags": [ "Company" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous page's `nextCursor` (ignored by /export).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, default 50, capped at 100 (ignored by /export).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by createdAt, default desc.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "actorId", "in": "query", "required": false, "description": "Filter to a single human actor.", "schema": { "type": "string", "format": "uuid" } }, { "name": "actorAgentId", "in": "query", "required": false, "description": "Filter to a single agent actor.", "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "query", "required": false, "description": "Comma-separated list of exact action strings.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by outcome.", "schema": { "type": "string", "enum": [ "ok", "denied", "error" ] } }, { "name": "entityType", "in": "query", "required": false, "description": "Filter by the affected entity type.", "schema": { "type": "string" } }, { "name": "entityId", "in": "query", "required": false, "description": "The history of one entity (an agent, a key…).", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Only entries at or after this instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Only entries at or before this instant. A bare date (`2026-09-01`) includes that whole day (UTC).", "schema": { "type": "string", "format": "date-time" } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search over action, entity type, actor name/email, agent name, target name/email and IP.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "qActions", "in": "query", "required": false, "description": "With `q`: comma-separated label keys (action with `.` replaced by `_`) whose translated label matched `q`; widens the search to those actions.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogPage" } } } }, "400": { "description": "Validation error, or an invalid cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/company/audit-log/export": { "get": { "operationId": "exportCompanyAuditLog", "summary": "Export the company audit journal as CSV", "description": "Company-admin only. Same filters as `GET /company/audit-log` (cursor/limit are ignored, sort is honoured), no pagination — hard-capped server-side; a capped export answers `X-Export-Truncated: true`. The export itself is journalled (`audit_log.exported`).", "tags": [ "Company" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous page's `nextCursor` (ignored by /export).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, default 50, capped at 100 (ignored by /export).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by createdAt, default desc.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "actorId", "in": "query", "required": false, "description": "Filter to a single human actor.", "schema": { "type": "string", "format": "uuid" } }, { "name": "actorAgentId", "in": "query", "required": false, "description": "Filter to a single agent actor.", "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "query", "required": false, "description": "Comma-separated list of exact action strings.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by outcome.", "schema": { "type": "string", "enum": [ "ok", "denied", "error" ] } }, { "name": "entityType", "in": "query", "required": false, "description": "Filter by the affected entity type.", "schema": { "type": "string" } }, { "name": "entityId", "in": "query", "required": false, "description": "The history of one entity (an agent, a key…).", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Only entries at or after this instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Only entries at or before this instant. A bare date (`2026-09-01`) includes that whole day (UTC).", "schema": { "type": "string", "format": "date-time" } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search over action, entity type, actor name/email, agent name, target name/email and IP.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "qActions", "in": "query", "required": false, "description": "With `q`: comma-separated label keys (action with `.` replaced by `_`) whose translated label matched `q`; widens the search to those actions.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV file (`text/csv`, `Content-Disposition: attachment`).", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Validation error, or an invalid cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/client/files": { "get": { "operationId": "listClientFiles", "summary": "List the company drive", "description": "Scoped by the node's `companyId` vault, not by author: every member of the company sees the same tree. Each node carries `authorName`, `isMine`, `canManage` and `canDelete` (false on another member's agent root folder) — the per-object rights, decided server-side.", "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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/client/files/usage": { "get": { "operationId": "getDriveUsage", "summary": "Total size and file count of the drive you can see", "description": "Same scope as `GET /client/files`, so the same numbers. Open to every member — unlike `/company/dashboard/storage`, which is admin-only.", "tags": [ "Files" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalBytes": { "type": "integer" }, "fileCount": { "type": "integer" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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" }, "fileSize": { "type": "integer", "minimum": 0, "maximum": 52428800, "description": "Size of the file about to be uploaded, in bytes. When sent, a file above the drive limit (50 MiB) is refused with 413 before any node is created." } } } } } }, "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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "parentId not found/owned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "FILE_TOO_LARGE — fileSize above the 50 MiB drive limit; no node created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/client/files/{nodeId}": { "patch": { "operationId": "updateFileNode", "summary": "Rename and/or move a file or folder", "description": "`parentId: null` moves the node back to the drive root; an absent `parentId` leaves the parent alone. At least one of `name`/`parentId` is required. Only the author or a company admin (`manageCompanyFiles`) may change a node.", "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", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "parentId": { "type": "string", "format": "uuid", "nullable": true, "description": "Destination folder, or null for the drive root." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileNode" } } } }, "400": { "description": "Nothing to change, destination is a file, or a folder would be moved inside its own subtree.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not the author, and not a company admin.", "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": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "deleteFileNode", "summary": "Delete a file or folder (recursive)", "description": "Cascades the whole subtree and removes the Storage objects. Author or company admin only.", "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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not the author, and not a company admin.", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/agents/{agentId}/cron-jobs/{jobId}/executions/{executionId}": { "get": { "operationId": "getCronJobExecutionOutput", "summary": "Read one execution's full output", "description": "On demand only (perf(projects-cron), PLAN-perf.md E3) — the one field the list above no longer carries (`output`, potentially the agent's full run content). 404, never 403, for a foreign agent, a job that is not this agent's, or an unknown execution id.", "tags": [ "Cron Jobs" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "description": "Cron job id", "schema": { "type": "string", "format": "uuid" } }, { "name": "executionId", "in": "path", "required": true, "description": "Execution id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution": { "$ref": "#/components/schemas/CronExecutionOutput" } }, "required": [ "execution" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "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 for api_key connectors." }, "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 / oauth_required / secret_required / invalid_credentials (a `secretInPath` key containing `/`, `?`, `#` or whitespace, or a `tokenExchange` key the provider refused to exchange for an access token) / config_invalid / config_host_not_public (a `publicHost` config field whose host is private, local or unresolvable — with the offending `field`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "provider_coming_soon — the provider is not open to clients yet (catalog `availability` is `coming_soon`: not functionally validated, admin status, or OAuth app not provisioned); a `message` explains it. Use POST /integrations/{key}/interest (\"Notify me\") instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_credentials — the provider did not answer the credential probe with a 2xx (nothing stored). `probeStatus` carries its HTTP status: 401/403 = key refused; another 4xx (422, 404…) = key or configuration (subdomain, account id) refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "provider_unavailable — the credential probe got no verdict (provider 5xx or 429, network error, timeout); nothing stored, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/integrations/connections/{id}": { "patch": { "operationId": "rotateIntegrationConnectionSecret", "summary": "Replace an integration connection's credential, in place", "description": "Admin only. The connection keeps its id, so every per-agent grant pointing at it survives — which is the point: DELETE destroys the connection and its secret, so disconnect/reconnect hands back a new id and strips every agent of its tools. `config` is re-validated against the connector's anchored patterns; omit it to keep the stored one. The connection goes back to `active`. Never returns credential material.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Connection id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "The new credential. Write-only — never read back." }, "config": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationConnection" } } } }, "400": { "description": "secret_required / invalid_credentials (a `secretInPath` key containing `/`, `?`, `#` or whitespace, or a `tokenExchange` key the provider refused to exchange for an access token) / config_invalid (with the offending `field`) / config_host_not_public (a `publicHost` config field that does not resolve to public addresses only, with the offending `field`) / not_connectable (internal connector) / oauth_required (oauth2 without apiKeyAlt — renew through the provider) / connection_revoked (reconnect instead)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": "provider_coming_soon — the provider is not open to clients yet (catalog `availability` is `coming_soon`: not functionally validated, admin status, or OAuth app not provisioned); a `message` explains it. Use POST /integrations/{key}/interest (\"Notify me\") instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_credentials — the provider did not answer the credential probe with a 2xx; the old credential stays in place. `probeStatus` carries its HTTP status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "provider_unavailable — the credential probe got no verdict (provider 5xx or 429, network error, timeout); the old credential stays in place, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" }, "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" } } } } } }, "400": { "description": "connection_not_deletable — a companyWide+nonDeletable native connection (e.g. 'projects') can't be disconnected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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 / config_host_not_public (a `publicHost` config field that does not resolve to public addresses only) — both with the offending `field`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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" } } } }, "409": { "description": "provider_coming_soon — the provider is not open to clients yet (catalog `availability` is `coming_soon`); a `message` explains it.", "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": [] } ], "x-atako-api-key": "write" } }, "/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_token_server_rejected|oauth_callback_param_missing|oauth_callback_param_invalid|oauth_exchange_failed` on failure) — never a JSON body. Multi-data-center providers (Zoho) also send the account's token server (`accounts-server`): it must be one of the connector's allow-listed origins, otherwise the connect is refused with `oauth_token_server_rejected` before any token call. Providers that name the connected tenant in the redirect (QuickBooks Online: `realmId`) must send it and it must match the connector's pattern, otherwise the connect is refused with `oauth_callback_param_missing` / `oauth_callback_param_invalid`, also before any token call.", "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" } }, { "name": "accounts-server", "in": "query", "required": false, "description": "Multi-data-center providers only (Zoho): origin of the account's token server, e.g. `https://accounts.zoho.eu`. Used for the code exchange and every refresh when allow-listed.", "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", "description": "Readable by the agent's owner or by an admin of the owner's company — the connections themselves belong to the company. 404 for anyone else.", "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "grantIntegration", "summary": "Grant (or update) an agent's access to an integration connection", "description": "Upsert on (agentId, connectionId). Allowed for the agent's owner or an admin of the owner's company.", "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" }, "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 / 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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no such agent, or the caller neither owns it nor administers its company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/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, or revoked session (SESSION_REVOKED).", "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": "SUBSCRIPTION_EXISTS — the company already has an active/past_due Stripe subscription; use /subscriptions/checkout/add-sessions instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "forbidden" } }, "/subscriptions/checkout/add-sessions": { "post": { "operationId": "addSubscriptionSeats", "summary": "Add seats to an existing subscription", "description": "Company-admin only. If a reduction is currently scheduled (AF-57), it is released first (`pendingReductionCanceled: true` in the response) before the increase is applied. The seats are granted only once the prorated invoice is paid: when the payment needs an extra step (3DS) or fails, `pendingPayment: true`, `activeAgentsPurchased` is unchanged and `invoiceUrl` is where to pay; the seats land when Stripe confirms the payment.", "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", "description": "The live seat count — unchanged while `pendingPayment` is true." }, "pendingActiveAgentsPurchased": { "type": "integer", "description": "Only when `pendingPayment` is true: the seat count once the invoice is paid." }, "pendingPayment": { "type": "boolean" }, "pendingReductionCanceled": { "type": "boolean" } } } } } }, "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, or revoked session (SESSION_REVOKED).", "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" } } } }, "409": { "description": "SUBSCRIPTION_CANCEL_SCHEDULED — a cancellation is scheduled (`cancelAt`); reactivate the subscription first.", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/subscriptions/agents/reduce": { "post": { "operationId": "reduceSubscriptionSeats", "summary": "Schedule a reduction of purchased seats for the end of the current period", "description": "Company-admin only. AF-57 (billing v2): never immediate — the company keeps its current seats until `pendingReductionEffectiveAt` (via a Stripe Subscription Schedule), no refund/credit. `activeAgentsPurchased` in the response is the unchanged, current live quantity. A new call while one is pending replaces it (same target = idempotent no-op).", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "minimum": 1, "description": "Target TOTAL seat count." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "activeAgentsPurchased": { "type": "integer", "description": "Unchanged — the current live quantity." }, "pendingActiveAgentsPurchased": { "type": "integer", "nullable": true }, "pendingReductionEffectiveAt": { "type": "string", "format": "date-time", "nullable": true }, "effect": { "type": "string", "enum": [ "scheduled" ] }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/subscriptions/agents/reduce/cancel": { "post": { "operationId": "cancelScheduledSeatReduction", "summary": "Cancel a pending scheduled seat reduction", "description": "Company-admin only. AF-57 (billing v2). Releases the Stripe Subscription Schedule and clears the pending columns.", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "activeAgentsPurchased": { "type": "integer" }, "pendingActiveAgentsPurchased": { "type": "null" }, "pendingReductionEffectiveAt": { "type": "null" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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 / NO_PENDING_REDUCTION", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "forbidden" } }, "/subscriptions/billing-interval": { "post": { "operationId": "scheduleBillingIntervalChange", "summary": "Schedule a monthly ↔ annual switch for the end of the current period", "description": "Company-admin only. Never immediate, no proration: the target interval is invoiced in full at `currentPeriodEnd`. Same plan, other interval. Requesting the current interval cancels a pending switch (`effect: canceled`); re-requesting the pending target is a no-op (`alreadyApplied: true`).", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "billingInterval" ], "properties": { "billingInterval": { "type": "string", "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "billingInterval": { "type": "string", "enum": [ "monthly", "annual" ], "nullable": true }, "pendingBillingInterval": { "type": "string", "enum": [ "monthly", "annual" ], "nullable": true }, "pendingBillingIntervalEffectiveAt": { "type": "string", "format": "date-time", "nullable": true }, "effect": { "type": "string", "enum": [ "scheduled", "canceled" ] }, "alreadyApplied": { "type": "boolean" } } } } } }, "400": { "description": "Invalid billingInterval / INTERVAL_NOT_AVAILABLE / PLAN_PRICE_NOT_CONFIGURED / NO_STRIPE_SUBSCRIPTION / Subscription is canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/subscriptions/billing-interval/cancel": { "post": { "operationId": "cancelBillingIntervalChange", "summary": "Cancel a pending billing interval switch", "description": "Company-admin only. Rebuilds the Stripe Subscription Schedule without the price change when a seat reduction is still pending on it, releases it otherwise.", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "billingInterval": { "type": "string", "enum": [ "monthly", "annual" ], "nullable": true }, "pendingBillingInterval": { "type": "string", "enum": [ "monthly", "annual" ], "nullable": true }, "pendingBillingIntervalEffectiveAt": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "400": { "description": "NO_STRIPE_SUBSCRIPTION / PLAN_PRICE_NOT_CONFIGURED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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 / NO_PENDING_INTERVAL_CHANGE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "forbidden" } }, "/subscriptions/licenses/preview": { "post": { "operationId": "previewLicenseChange", "summary": "Preview the billing effect of a target total seat count", "description": "Company-admin only, no side effect. AF-57 (billing v2). An increase previews the immediate Stripe proration charge; a reduction previews the scheduled change with nothing due today.", "tags": [ "Subscriptions" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "type": "integer", "minimum": 1, "description": "Target TOTAL seat count." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "currentQuantity": { "type": "integer" }, "newQuantity": { "type": "integer" }, "deltaQuantity": { "type": "integer" }, "immediate": { "type": "boolean" }, "dueTodayCents": { "type": "integer" }, "currency": { "type": "string" }, "nextInvoiceAmountCents": { "type": "integer" }, "nextInvoiceDate": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time", "description": "Same value as nextInvoiceDate — meaningful (non-immediate) for a reduction." }, "unitAmountCents": { "type": "integer" } } } } } }, "400": { "description": "quantity must be a positive integer / NO_CHANGE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/subscriptions/checkout/verify": { "post": { "operationId": "verifySubscriptionCheckout", "summary": "Sync the subscription with Stripe after a Checkout redirect", "description": "Idempotent. A plan checkout returns the agent subscription (and provisions the recharge chosen with it); a recharge checkout (`metadata.type = credit_subscription`) returns the credit subscription.", "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": { "oneOf": [ { "$ref": "#/components/schemas/CompanySubscription" }, { "$ref": "#/components/schemas/CreditSubscription" } ] } } } }, "400": { "description": "sessionId required / Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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" } } } }, "409": { "description": "Recharge not active on Stripe yet — nothing provisioned.", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/subscriptions/invoices": { "get": { "operationId": "listInvoices", "summary": "List Stripe invoices for your company", "description": "Company-admin only. Every invoice of the company Stripe customer (subscriptions and credit top-ups). `[]` 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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/subscriptions/billing-details": { "get": { "operationId": "getBillingDetails", "summary": "Get the company billing details (legal name, address, tax IDs)", "description": "Company-admin only. `null` before the first purchase or when USE_STRIPE=false. The legal name and address are the ones stored by the app (`companies.billing_legal_name`, `companies.billing_address`), never what a Checkout attempt (even declined) may have written on the Stripe customer. No stored address yet → seeded from the Stripe customer.", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CustomerBillingDetails" } ], "nullable": true } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/subscriptions/checkout/canceled": { "post": { "operationId": "restoreLegalNameAfterCanceledCheckout", "summary": "Restore the legal name and address after a Checkout left through its cancel URL", "description": "Company-admin only. A Checkout attempt (even a declined one) may write the cardholder name and the typed address on the Stripe customer; the stored legal name and address are put back. `restored: false` when there is no Stripe customer, neither stored legal name nor address, or USE_STRIPE=false.", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "restored": { "type": "boolean" } }, "required": [ "restored" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "forbidden" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "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 (national trunk 0 dropped) and silently dropped if unparsable — never blocks signup; an existing phone is never overwritten (PATCH changes it).", "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", "enum": [ "fr", "en", "de", "es", "it", "pt-BR", "nl", "pl", "sv", "da", "tr", "ja", "ko" ], "description": "UI locale at signup. Applied on insert only — never overwrites an existing value." }, "acceptTerms": { "type": "boolean", "enum": [ true ], "description": "Terms checkbox ticked on /signup. Server stamps `termsAcceptedAt` and the currently published terms version (`termsVersionId`) — first acceptance only, never overwritten." } } } } } }, "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": "Unauthorized, or ACCOUNT_NOT_FOUND — no `users` row and the Supabase Auth identity no longer exists (deleted account): nothing is recreated.", "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" } } } }, "503": { "description": "AUTH_UNAVAILABLE — no `users` row and Supabase Auth could not confirm the identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" }, "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", "enum": [ "fr", "en", "de", "es", "it", "pt-BR", "nl", "pl", "sv", "da", "tr", "ja", "ko" ], "description": "Preferred UI/email locale — Settings → Appearance writes it here." } } } } } }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "forbidden" } }, "/users/me/email-preferences": { "get": { "operationId": "getMyEmailPreferences", "summary": "Get your optional-email preferences", "description": "The three declinable families and whether each still reaches you. Essential email — sign-in codes, receipts, security alerts, terms updates — is never listed, because it has no opt-out.", "tags": [ "Users" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "preferences" ], "properties": { "preferences": { "type": "array", "items": { "type": "object", "required": [ "key", "subscribed" ], "properties": { "key": { "type": "string", "enum": [ "welcomeD2", "welcomeD5", "digest", "survey" ] }, "subscribed": { "type": "boolean", "description": "True while this family still reaches the caller." } } } } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "patch": { "operationId": "updateMyEmailPreferences", "summary": "Subscribe to or unsubscribe from an optional-email family", "description": "Expressed as SUBSCRIBED (`{\"digest\": false}` stops the activity digest). Merges, so a payload naming one family leaves the others untouched. An unknown family is rejected rather than ignored.", "tags": [ "Users" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "welcomeD2": { "type": "boolean" }, "welcomeD5": { "type": "boolean" }, "digest": { "type": "boolean" }, "survey": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "preferences" ], "properties": { "preferences": { "type": "array", "items": { "type": "object", "required": [ "key", "subscribed" ], "properties": { "key": { "type": "string", "enum": [ "welcomeD2", "welcomeD5", "digest", "survey" ] }, "subscribed": { "type": "boolean", "description": "True while this family still reaches the caller." } } } } } } } } }, "400": { "description": "Unknown family or non-boolean value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/users/me/tour-seen": { "post": { "operationId": "markMyTourSeen", "summary": "Mark the guided tour as seen", "description": "Finished or skipped: the web app stops opening it on its own. Idempotent — the first date is kept.", "tags": [ "Users" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "tourSeenAt": { "type": "string", "format": "date-time" } }, "required": [ "tourSeenAt" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/users/me/storey-tours/{storey}/seen": { "post": { "operationId": "markMyStoreyTourSeen", "summary": "Mark a storey's guided tour as seen", "description": "Finished or skipped: the web app stops opening it when the user reaches that storey. Idempotent — the first date is kept.", "tags": [ "Users" ], "parameters": [ { "name": "storey", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "dashboard", "projects", "floor", "context" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "storeyToursSeen": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" } } }, "required": [ "storeyToursSeen" ] } } } }, "400": { "description": "Unknown storey.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/users/me/tours/reset": { "post": { "operationId": "resetMyTours", "summary": "Reset the guided tours", "description": "Settings → Appearance: every guided tour is due again — the welcome tour at the next app load, each storey the next time the user reaches it. Idempotent.", "tags": [ "Users" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "tourSeenAt": { "type": "string", "format": "date-time", "nullable": true }, "storeyToursSeen": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" } } }, "required": [ "tourSeenAt", "storeyToursSeen" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/users/me/impersonation": { "get": { "operationId": "getImpersonationStatus", "summary": "Is this session an admin impersonation?", "description": "True only for a session an Atako operator opened as the user (back-office hijack). Lets every tab of that session show the impersonation banner.", "tags": [ "Users" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "impersonating": { "type": "boolean" } }, "required": [ "impersonating" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/users/me/impersonation/end": { "post": { "operationId": "endImpersonation", "summary": "Leave an admin impersonation session", "description": "Only meaningful from a session an Atako operator opened as the user (back-office hijack): closes it and journals the exit. Any other session answers 404.", "tags": [ "Users" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_IMPERSONATING", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "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", "pattern": "^https?://", "description": "http:// or https:// only." } } } } } } } } }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/company/me/members": { "get": { "operationId": "listCompanyMembers", "summary": "List company members", "description": "Company-admin only (since 2026-09-18 — see `docs/concepts/permissions.md`; it used to be open to any member).", "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`ALREADY_IN_COMPANY` — the caller joined another company after this invitation was issued. A user has at most one.", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/teams/assignable": { "get": { "operationId": "listAssignableTeams", "summary": "List the teams you can attach an agent to", "description": "Every team of your live company (an owner or a company admin may place an agent in any of them), or just your own teams if you have no company.", "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, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "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, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/floor/state": { "get": { "operationId": "getFloorState", "summary": "Aggregated Agent Floor state (teams, agents, members)", "description": "Single-shot read for the Agent Floor 3D scene: your company's teams (with org-chart positions), non-completed agents (with a derived managerHumanId), and members. Open to any company member — admin and member get the exact same shape. 404 (not 403) when you have no company, so the route is invisible rather than merely blocked. The floor is open to every company.", "tags": [ "Floor" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FloorState" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/search": { "get": { "operationId": "searchEverything", "summary": "Global search across your company (agents, teams, people, projects, cards, wiki pages, sessions, cron jobs, webhook endpoints, files, integrations)", "description": "One query, twelve kinds, one flat list — what the application's ⌘K bar calls on every keystroke. Case- and accent-insensitive substring match on each kind's display name, at most 8 rows per kind, then `limit` overall. Scope is exactly what the caller can already list, kind by kind: agents (completed ones included, flagged `archived`), teams and members of your company; your OWN chat sessions only; webhook endpoints and cron jobs of your company's agents; projects (archived flagged), non-archived cards and wiki pages of your company; your OWN file library; integration connections of your company or created by you. Admin-only surfaces (audit log, dashboard) are never searched, so admin and member get the same shape. 404 (not 403) when you have no company.", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "What to look for. Folded (lower-case, accents stripped) before matching.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "limit", "in": "query", "required": false, "description": "Overall cap on the returned list, applied after the per-kind cap of 8.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 60 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "agent", "team", "member", "session", "webhookEndpoint", "cronJob", "project", "card", "wikiPage", "file", "folder", "integration" ] }, "id": { "type": "string", "format": "uuid" }, "label": { "type": "string", "description": "The object's own name, never translated." }, "context": { "type": "string", "nullable": true, "description": "A readable parent: the agent's team, a session's agent, a card's project and column." }, "status": { "type": "string", "nullable": true, "description": "An enum value for the client to translate (agent status, project status, `blocked`, `enabled`/`disabled`, connection status)." }, "agentId": { "type": "string", "format": "uuid", "description": "sessions, webhook endpoints, cron jobs" }, "projectId": { "type": "string", "format": "uuid", "description": "cards, wiki pages" }, "archived": { "type": "boolean", "description": "completed agent, archived session or project" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "kind", "id", "label", "context", "status", "updatedAt" ] } } }, "required": [ "results" ] } } } }, "400": { "description": "`q` missing, empty or longer than 80 characters; `limit` out of 1..100.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/floor/past-agents": { "get": { "operationId": "getFloorPastAgents", "summary": "Completed agents of your company (« ghosts » mode)", "description": "The agents `GET /floor/state` deliberately leaves out: the completed ones, most recently ended first (agents with no end date come last). A route of its own rather than a flag on `/floor/state`, because that read feeds the reconciliation of the stored floor layout and must never be told about departed agents. Deliberately cheap: one query on the agents table, no org-chart join, hence no `managerHumanId` — a completed agent holds no position anyway. Capped at 60 rows, with no cursor: this is a look back at the recent past, not an export. Open to any company member — 404 (not 403) when you have no company, exactly like `/floor/state`.", "tags": [ "Floor" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "completed" ] }, "teamId": { "type": "string", "format": "uuid", "nullable": true }, "avatarSeed": { "type": "string", "description": "agents.image — mascot filename in apps/web/public/aiygents." }, "createdAt": { "type": "string", "format": "date-time" }, "lastActivityAt": { "type": "string", "format": "date-time", "nullable": true, "description": "agents.lastHeartbeatAt." }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "When the agent was ended; null when it was never recorded." }, "clientId": { "type": "string", "format": "uuid", "description": "Owner of the agent." } }, "required": [ "id", "name", "status", "teamId", "avatarSeed", "createdAt", "lastActivityAt", "endDate", "clientId" ] } } }, "required": [ "agents" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/floor/layout": { "put": { "operationId": "putFloorLayout", "summary": "Replace the stored floor arrangement", "description": "Replaces the whole document, creating the row on the company's first edit (version 1). Every id must belong to the caller's company and two occupants of the SAME team cannot share a `slot` — either breach is a 400 with an explicit message, never a silent drop. `version` is an optional optimistic lock: when given and no longer current, 409 Version conflict rather than overwriting a colleague's whole rearrangement.", "tags": [ "Floor" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pods": { "type": "array", "items": { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid" }, "x": { "type": "number" }, "z": { "type": "number" } }, "required": [ "teamId", "x", "z" ] } }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slot": { "type": "integer", "minimum": 0, "maximum": 199, "description": "Desk index inside the pod of the occupant's own team." } }, "required": [ "id", "slot" ] } }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slot": { "type": "integer", "minimum": 0, "maximum": 199, "description": "Desk index inside the pod of the occupant's own team." } }, "required": [ "id", "slot" ] } }, "version": { "type": "integer", "minimum": 0, "description": "Expected current version. Omit for last-writer-wins." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "layout": { "$ref": "#/components/schemas/FloorLayout" }, "version": { "type": "integer" } }, "required": [ "layout", "version" ] } } } }, "400": { "description": "Malformed body, or an id/slot the company cannot accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only — every floor write is reserved to a company admin.", "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": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "deleteFloorLayout", "summary": "Back to the automatic floor layout", "description": "Drops the stored row — the plateau is derived again. Idempotent: 204 even when nothing was ever stored (the outcome asked for is reached either way).", "tags": [ "Floor" ], "responses": { "204": { "description": "Deleted (or nothing to delete)." }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only — every floor write is reserved to a company admin.", "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": [] } ], "x-atako-api-key": "write" } }, "/floor/agents/{id}/position": { "patch": { "operationId": "patchFloorAgentPosition", "summary": "Move one agent on the floor", "description": "Unitary move. `teamId` is ORGANISATION data: when it differs from the agent's current team the `agents.team_id` column is updated, while only the desk goes into the document. `teamId: null` moves the agent to the teamless front row and removes its document entry (a slot means nothing there). An agent of another company — or a `teamId` of another company — answers 404, never 403: the response must not confirm that the id exists elsewhere.", "tags": [ "Floor" ], "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", "slot" ], "properties": { "teamId": { "type": "string", "format": "uuid", "nullable": true }, "slot": { "type": "integer", "minimum": 0, "maximum": 199, "description": "Desk index inside the pod of the occupant's own team." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "layout": { "$ref": "#/components/schemas/FloorLayout" }, "version": { "type": "integer" } }, "required": [ "layout", "version" ] } } } }, "400": { "description": "Malformed body, or the desk is already taken on that team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only — every floor write is reserved to a company admin.", "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": [] } ], "x-atako-api-key": "write" } }, "/floor/teams/{id}/position": { "patch": { "operationId": "patchFloorTeamPosition", "summary": "Move a team platform on the floor", "description": "Sets the pod centre, in world units, bounded exactly like the stored document.", "tags": [ "Floor" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "string" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "x", "z" ], "properties": { "x": { "type": "number", "minimum": -500, "maximum": 500 }, "z": { "type": "number", "minimum": -500, "maximum": 500 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "layout": { "$ref": "#/components/schemas/FloorLayout" }, "version": { "type": "integer" } }, "required": [ "layout", "version" ] } } } }, "400": { "description": "Malformed body or out-of-bounds coordinates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only — every floor write is reserved to a company admin.", "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": [] } ], "x-atako-api-key": "write" } }, "/floor/agents/{id}/place": { "post": { "operationId": "placeFloorAgent", "summary": "Drop a not-yet-placed agent on a team", "description": "Reserved to an agent that is nowhere yet — no team, or still provisioning. An already-installed agent gets 409 Already placed: moving it is the OTHER gesture (PATCH /floor/agents/{id}/position). `slot` omitted = first free desk of the team, computed server-side.", "tags": [ "Floor" ], "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" }, "slot": { "type": "integer", "minimum": 0, "maximum": 199, "description": "Desk index inside the pod of the occupant's own team." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "layout": { "$ref": "#/components/schemas/FloorLayout" }, "version": { "type": "integer" } }, "required": [ "layout", "version" ] } } } }, "400": { "description": "Malformed body, or the desk is already taken on that team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only — every floor write is reserved to a company admin.", "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": "Already placed — or the team has no free desk left.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/organization/chart": { "get": { "operationId": "getOrgChart", "summary": "The company org chart", "description": "The only read the client needs: it carries the drawn tree, the warnings, AND the three raw lists that fill the edit pickers — no second call to display a screen. Open to any company member; `canEdit` reports whether the caller may use the write operations. 404 (not 403) when you have no company, so the route is invisible rather than merely blocked.", "tags": [ "Organization" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgChart" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/organization/candidates": { "get": { "operationId": "listOrgCandidates", "summary": "Who may be named manager, or team lead", "description": "Exactly one of `subject` (candidates to manage that member) or `teamLead` (candidates to lead that team) — neither or both is a 400. Blocked candidates are returned too, with their `blockedReason`. Admin only: it is the list an editor unrolls, and it only means something to somebody who may pick from it.", "tags": [ "Organization" ], "parameters": [ { "name": "subject", "in": "query", "required": false, "description": "The member to find a manager for, as `human:` or `agent:`.", "schema": { "type": "string", "pattern": "^(human|agent):.+$" } }, { "name": "teamLead", "in": "query", "required": false, "description": "The team to find a lead for.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/OrgCandidate" } } }, "required": [ "candidates" ] } } } }, "400": { "description": "Provide exactly one of `subject` or `teamLead`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/organization/teams/{id}/lead": { "put": { "operationId": "setOrgTeamLead", "summary": "Designate (or clear) a team lead", "description": "The structural gesture: a team's agents inherit this lead, so fifteen agents over three teams are three links to keep, not fifteen. `lead: null` clears the designation — the team then falls back to the company root, which is a warning (`team-lead`) and not an error. An agent may lead a team, but only if somebody is responsible for it in turn, otherwise the whole team would inherit a chain leading nowhere (`ORG_NO_HUMAN_MANAGER`).", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead" ], "properties": { "lead": { "allOf": [ { "$ref": "#/components/schemas/OrgRef" } ], "nullable": true } } } } } }, "responses": { "200": { "description": "The recomputed chart — identical shape to GET /organization/chart.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgChart" } } } }, "400": { "description": "Validation error, or a refused hierarchy: `ORG_CYCLE` (the link would close a loop) / `ORG_NO_HUMAN_MANAGER` (somebody would end up with no person responsible for them). The body carries the bare CODE so the client can say which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only — every organisation write is reserved to a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company, an unknown id, or one belonging to another company (`TEAM_NOT_FOUND` / `ORG_REF_NOT_FOUND`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/organization/agents/{id}/manager": { "put": { "operationId": "setOrgAgentManager", "summary": "Give an agent its own manager", "description": "The exception, not the ordinary case: it pulls the agent out of its team's line. `manager: null` puts it back into that line (inheritance). Refused when it would close a loop (`ORG_CYCLE`) or when nobody human would end up above the agent (`ORG_NO_HUMAN_MANAGER`) — an agent under an agent is allowed; an agent under an agent under nobody is what the rule forbids.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "manager" ], "properties": { "manager": { "allOf": [ { "$ref": "#/components/schemas/OrgRef" } ], "nullable": true } } } } } }, "responses": { "200": { "description": "The recomputed chart — identical shape to GET /organization/chart.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgChart" } } } }, "400": { "description": "Validation error, or a refused hierarchy: `ORG_CYCLE` (the link would close a loop) / `ORG_NO_HUMAN_MANAGER` (somebody would end up with no person responsible for them). The body carries the bare CODE so the client can say which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only — every organisation write is reserved to a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company, an unknown id, or one belonging to another company (`TEAM_NOT_FOUND` / `ORG_REF_NOT_FOUND`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/organization/members/{userId}/manager": { "put": { "operationId": "setOrgMemberManager", "summary": "Give a person their manager", "description": "A USER id, never an OrgRef: the typing carries half the cardinal rule — a person answers to a person, or to nobody. `managerUserId: null` makes them a root of the chart.", "tags": [ "Organization" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "User id of the member", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "managerUserId" ], "properties": { "managerUserId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "The recomputed chart — identical shape to GET /organization/chart.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgChart" } } } }, "400": { "description": "Validation error, or a refused hierarchy: `ORG_CYCLE` (the link would close a loop) / `ORG_NO_HUMAN_MANAGER` (somebody would end up with no person responsible for them). The body carries the bare CODE so the client can say which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only — every organisation write is reserved to a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company, an unknown id, or one belonging to another company (`TEAM_NOT_FOUND` / `ORG_REF_NOT_FOUND`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/organization/agents/{id}/team": { "put": { "operationId": "setOrgAgentTeam", "summary": "Move an agent to another team", "description": "An ORGANISATION write, not a floor one: changing team changes the inherited manager, so it can be refused (`ORG_CYCLE`, `ORG_NO_HUMAN_MANAGER`) where PATCH /floor/agents/{id}/position merely picks a desk. `teamId: null` sends the agent back to the virtual « unassigned » group.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId" ], "properties": { "teamId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "The recomputed chart — identical shape to GET /organization/chart.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgChart" } } } }, "400": { "description": "Validation error, or a refused hierarchy: `ORG_CYCLE` (the link would close a loop) / `ORG_NO_HUMAN_MANAGER` (somebody would end up with no person responsible for them). The body carries the bare CODE so the client can say which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin only — every organisation write is reserved to a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company, an unknown id, or one belonging to another company (`TEAM_NOT_FOUND` / `ORG_REF_NOT_FOUND`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/projects": { "get": { "operationId": "listProjects", "summary": "List your company's projects", "description": "The storey's table: each project with aggregate counts computed in SQL and a short participant list for the avatar stack — never the cards themselves (use GET /projects/{id}). Newest first. Archived projects are left out by default; `archived=only` lists them alone and `archived=include` lists everything.", "tags": [ "Projects" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "archived", "in": "query", "required": false, "description": "What the list does with archived projects. Deliberately NOT called `status`: a project already has a `status` (active/paused/done) and \"archived\" is not one of its values — it is the presence of `archivedAt`.", "schema": { "type": "string", "enum": [ "exclude", "only", "include" ], "default": "exclude" } }, { "name": "includeArchived", "in": "query", "required": false, "description": "Deprecated, kept for existing callers — use `archived`. `true` means `archived=include`; `archived` wins when both are sent. Anything else is a 400, so `?includeArchived=false` cannot silently mean the opposite.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "space", "in": "query", "required": false, "description": "Only projects whose space equals this value exactly (after trim and whitespace collapsing). Cannot be combined with `withoutSpace=true`.", "schema": { "type": "string", "maxLength": 60 } }, { "name": "withoutSpace", "in": "query", "required": false, "description": "`true` lists only projects that have no space. Sending it together with `space` is a 400.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSummary" } }, "total": { "type": "integer", "description": "Total matching projects, ignoring limit/offset." }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "projects", "total", "limit", "offset" ] } } } }, "400": { "description": "Invalid pagination, archived or includeArchived value, or `space` combined with `withoutSpace=true`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "createProject", "summary": "Create a project", "description": "One transaction: the project, its members, the starting columns (a starting point only — from then on the columns belong to the project) and the wiki home page with its first revision. `participants` is the UI's flat list of ids: each is resolved as either a company human or a company agent. An agent's membership is checked through its owner's live `users.companyId`, never the stale `agents.companyId` snapshot. Send `starter` to name that starting point in the user's own language — the API has no translation catalogue and falls back to its French defaults when you omit it. Returns the full project.", "tags": [ "Projects" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 20000, "default": "" }, "tone": { "$ref": "#/components/schemas/ProjectTone" }, "space": { "type": "string", "nullable": true, "description": "Free-form space label: trimmed, inner whitespace collapsed, max 60 characters after that (400 beyond). `null` or `\"\"` means no space." }, "participants": { "type": "array", "maxItems": 100, "items": { "type": "string", "format": "uuid" }, "description": "Ids of company members or company agents, mixed — the server sorts them out." }, "starter": { "$ref": "#/components/schemas/ProjectStarter" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Validation error, or INVALID_PARTICIPANTS (the response lists the offending ids in `invalid`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{id}": { "get": { "operationId": "getProject", "summary": "Get a project in full", "description": "Participants, columns, non-archived cards (with their comments) and the wiki rebuilt as a tree — the single read the whole Projects UI runs on.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Malformed project id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "patch": { "operationId": "updateProject", "summary": "Update a project", "description": "At least one field — an empty patch would bump `updatedAt` and reorder the list for nothing.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 20000 }, "tone": { "$ref": "#/components/schemas/ProjectTone" }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "space": { "type": "string", "nullable": true, "description": "Free-form space label: trimmed, inner whitespace collapsed, max 60 characters after that (400 beyond). `null` or `\"\"` means no space. Send null or \"\" to clear it." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Validation error / empty body / malformed id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "archiveProject", "summary": "Archive a project (never deletes)", "description": "Sets `archivedAt`. A real delete would cascade through the board, the cards, the comments and the whole wiki history — what the team learned would go with what it had left to do. Company admins and the project's creator only.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The archived project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Malformed project id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{id}/restore": { "post": { "operationId": "restoreProject", "summary": "Reopen an archived project", "description": "The exact inverse of DELETE /projects/{id}: `archivedAt` goes back to null and nothing else moves — archiving destroyed nothing, so the project comes back as it left. Same rights as archiving (company admins and the project's creator). Reopening a project that is not archived is a 409: the project exists and you can see it, it is the gesture that makes no sense.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The reopened project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Malformed project id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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" } } } }, "409": { "description": "NOT_ARCHIVED — the project is already open.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/projects/{id}/columns": { "post": { "operationId": "createProjectColumn", "summary": "Add a column to a project's board", "description": "Appended at the end — a new column has no reason to slip into a flow the team already ordered.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "$ref": "#/components/schemas/ProjectColumnKind" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectColumn" } } } }, "400": { "description": "Validation error / malformed id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{id}/columns/order": { "patch": { "operationId": "reorderProjectColumns", "summary": "Rewrite the board's column order", "description": "The COMPLETE order, not a move: the list must match the project's columns exactly (no duplicate, nothing missing, nothing foreign) or it is rejected as COLUMN_ORDER_MISMATCH — a partial list would leave the uncited columns on old positions, producing an order neither side chose. Applied in one transaction.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "columnIds" ], "properties": { "columnIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectColumn" } } }, "required": [ "columns" ] } } } }, "400": { "description": "Validation error / COLUMN_ORDER_MISMATCH.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{id}/columns/{columnId}": { "patch": { "operationId": "updateProjectColumn", "summary": "Rename a column or change its kind", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "columnId", "in": "path", "required": true, "description": "Column id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "$ref": "#/components/schemas/ProjectColumnKind" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectColumn" } } } }, "400": { "description": "Validation error / malformed id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "deleteProjectColumn", "summary": "Delete an empty column", "description": "Refused while the column still holds cards (archived ones included — they would go in the same cascade). The obstacle is named rather than worked around: moving the cards elsewhere would change their state on the team's behalf, since a card's state IS its column.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "columnId", "in": "path", "required": true, "description": "Column id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Malformed id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": "COLUMN_NOT_EMPTY — the response carries the blocking card count in `cards`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/projects/{id}/members": { "get": { "operationId": "listProjectMembers", "summary": "List a project's participants", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectParticipant" } } } } }, "400": { "description": "Malformed project id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "addProjectMember", "summary": "Add a human or an agent to a project", "description": "Exactly one of `userId` / `agentId`. An id presented as a `userId` that turns out to be an agent (or the reverse) is rejected, not silently requalified.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "maxLength": 100, "default": "", "description": "Free text shown on the card — unrelated to platform permissions." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectParticipant" } } } }, "400": { "description": "Validation error / INVALID_MEMBER (not a human or agent of your company).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": "ALREADY_MEMBER", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/projects/{id}/members/{memberId}": { "patch": { "operationId": "updateProjectMember", "summary": "Change a participant's role on the project", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "memberId", "in": "path", "required": true, "description": "Participant id (project_members row)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "maxLength": 100 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectParticipant" } } } }, "400": { "description": "Validation error / malformed id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "removeProjectMember", "summary": "Remove a participant from a project", "description": "Cards assigned to them become unassigned rather than disappearing — `project_cards.assignee_id` is ON DELETE SET NULL.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "memberId", "in": "path", "required": true, "description": "Participant id (project_members row)", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Malformed id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/cards": { "post": { "operationId": "createProjectCard", "summary": "Add a card to a column", "description": "The card lands at the bottom of the column it is created in — a new task does not push itself ahead of work the team already ordered. The column must belong to this project, and an assignee must already be a participant of it.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "columnId", "title" ], "properties": { "columnId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "maxLength": 20000 }, "assigneeId": { "type": "string", "format": "uuid", "nullable": true, "description": "A participant id (project_members row). null or omitted leaves the card unclaimed." }, "priority": { "$ref": "#/components/schemas/ProjectCardPriority" }, "labels": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "checklist": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ProjectCardChecklistItem" } }, "dueAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 with offset. The API never speaks in milliseconds." }, "blocked": { "type": "string", "minLength": 1, "maxLength": 500, "nullable": true, "description": "The reason the card cannot move. An empty string is refused: a card is blocked by saying why, or not at all." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/ProjectCard" } }, "required": [ "card" ] } } } }, "400": { "description": "Validation error, `column_not_in_project`, or `assignee_not_member`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/cards/{cardId}": { "patch": { "operationId": "updateProjectCard", "summary": "Edit a card", "description": "At least one known field. An omitted field is left alone; an explicit `null` on `assigneeId`, `dueAt` or `blocked` clears it — that is how a card is unassigned, unscheduled or unblocked. Moving a card is a separate operation.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardId", "in": "path", "required": true, "description": "Card id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "maxLength": 20000 }, "assigneeId": { "type": "string", "format": "uuid", "nullable": true }, "priority": { "$ref": "#/components/schemas/ProjectCardPriority" }, "blocked": { "type": "string", "minLength": 1, "maxLength": 500, "nullable": true }, "labels": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "checklist": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ProjectCardChecklistItem" } }, "dueAt": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/ProjectCard" } }, "required": [ "card" ] } } } }, "400": { "description": "Validation error, a body with no editable field, `column_not_in_project`, or `assignee_not_member`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "archiveProjectCard", "summary": "Archive a card (never deletes)", "description": "A card carries a discussion and the decisions taken on it, so it is set aside rather than destroyed. Its place in the column closes immediately — an archived card holds no rank — and the column's new contents come back with it.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardId", "in": "path", "required": true, "description": "Card id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The archived card, plus the column it left.", "content": { "application/json": { "schema": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/ProjectCard" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectColumnOrder" } } }, "required": [ "card", "columns" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/cards/{cardId}/move": { "patch": { "operationId": "moveProjectCard", "summary": "Move a card to a column and a position", "description": "The one gesture that changes a card's state, since the state IS the column. Kept apart from editing so that renaming a card never becomes a transactional write across the whole board. `position` is the rank the card takes among the live cards of the target column, counted without itself; a rank past the end simply lands it at the bottom.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardId", "in": "path", "required": true, "description": "Card id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "columnId", "position" ], "properties": { "columnId": { "type": "string", "format": "uuid", "description": "Target column — must belong to this project." }, "position": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "The moved card, plus the new contents of the source and target columns (one entry when it stayed in the same column).", "content": { "application/json": { "schema": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/ProjectCard" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectColumnOrder" } } }, "required": [ "card", "columns" ] } } } }, "400": { "description": "Validation error, malformed id, or `column_not_in_project`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/cards/{cardId}/restore": { "post": { "operationId": "restoreProjectCard", "summary": "Bring an archived card back", "description": "The card returns to the bottom of the column it left: its old rank belongs to somebody else by now.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardId", "in": "path", "required": true, "description": "Card id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The restored card, plus its column's new contents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/ProjectCard" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectColumnOrder" } } }, "required": [ "card", "columns" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown card, or a card that is not archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/cards/archived": { "get": { "operationId": "listArchivedProjectCards", "summary": "List the archived cards of a project", "description": "Most recently archived first. The project detail leaves archived cards out, yet they still hold their column (`COLUMN_NOT_EMPTY`): this list is the way to find and restore them.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "cards" ], "properties": { "cards": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ProjectCard" }, { "type": "object", "required": [ "archivedAt" ], "properties": { "archivedAt": { "type": "string", "format": "date-time" } } } ] } } } } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/projects/{projectId}/cards/{cardId}/comments": { "get": { "operationId": "listProjectCardComments", "summary": "Read a card's discussion", "description": "Oldest first — a thread is read in the order it was written. Paginated for cards whose discussion outgrew the panel.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardId", "in": "path", "required": true, "description": "Card id", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectCardComment" } }, "total": { "type": "integer", "description": "Comments on the card in all, ignoring limit/offset." }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "comments", "total", "limit", "offset" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "addProjectCardComment", "summary": "Comment on a card", "description": "The author is the caller, never a field of the body — nobody signs a comment in somebody else's name. The display name is frozen into the comment at write time, so the thread survives that person leaving the company.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardId", "in": "path", "required": true, "description": "Card id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/ProjectCardComment" } }, "required": [ "comment" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/cards/{cardId}/comments/{commentId}": { "patch": { "operationId": "updateProjectCardComment", "summary": "Edit your own comment", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardId", "in": "path", "required": true, "description": "Card id", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "Comment id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/ProjectCardComment" } }, "required": [ "comment" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The comment belongs to somebody else — it is visible to the whole project, editable only by its author.", "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": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "deleteProjectCardComment", "summary": "Delete your own comment", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardId", "in": "path", "required": true, "description": "Card id", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "Comment id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The comment belongs to somebody else.", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/wiki": { "get": { "operationId": "getProjectWikiTree", "summary": "Read a project's wiki table of contents", "description": "The sidebar's view: titles and nesting, with how many times each page was rewritten. Ask for `withContent=true` only when you actually want every page's Markdown — the summary stays light by default.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "withContent", "in": "query", "required": false, "description": "Include each page's full Markdown. Anything other than true/false is a 400.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectWikiNode" } } }, "required": [ "pages" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "createProjectWikiPage", "summary": "Create a wiki page", "description": "The page and its first revision are written together — a page with no history would be a page whose origin is already lost. Omit `parentId` (or send null) for a page at the root; omit `path` to have one derived from the title and the parent.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "content": { "type": "string", "maxLength": 200000, "description": "Markdown. Bounded so an agent writing in a loop cannot fill the table." }, "parentId": { "type": "string", "format": "uuid", "nullable": true }, "path": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/ProjectWikiPageDetail" } }, "required": [ "page" ] } } } }, "400": { "description": "Validation error, malformed id, or a `parentId` that is not a page of this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/wiki/{pageId}": { "get": { "operationId": "getProjectWikiPage", "summary": "Open a wiki page", "description": "Its current text, a slice of its history (newest first) and its sub-pages. `content` is always what `history[0]` holds.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "description": "Wiki page id", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "How many revisions to return with the page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Accepted and validated; paging through the history is done on the revisions operation.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/ProjectWikiPageDetail" } }, "required": [ "page" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "patch": { "operationId": "updateProjectWikiPage", "summary": "Rename a wiki page and/or write a new revision", "description": "Send `title`, `content`, or both — a patch asking for neither would be a 200 that wrote nothing. Rewriting the text exactly as it already stands is refused for the same reason: it would look like a revision that was never recorded. `message` is the note left on the revision, like a commit message.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "description": "Wiki page id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "content": { "type": "string", "maxLength": 200000 }, "message": { "type": "string", "maxLength": 500 }, "autosave": { "type": "boolean", "description": "Editor autosave: extends the newest revision when it belongs to the same author and the same `sessionId`, carries no message and is less than 10 minutes old." }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The editor writing (one per browser tab). Two sessions never share a revision." }, "baseSha": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The sha of the head revision the caller edited on. If the page changed since, nothing is written and the answer is 409 `WIKI_CONFLICT`." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/ProjectWikiPageDetail" } }, "required": [ "page" ] } } } }, "400": { "description": "Validation error, malformed id, or content identical to the current revision (nothing to record).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": "The page changed since `baseSha`: `error` is `WIKI_CONFLICT` and `page` is the current page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "WIKI_CONFLICT" ] }, "page": { "$ref": "#/components/schemas/ProjectWikiPageDetail" } }, "required": [ "error", "page" ] } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "deleteProjectWikiPage", "summary": "Delete a wiki page and everything under it", "description": "Company admins only. This is the one wiki gesture no revision can undo: the page leaves with its sub-pages and all of their history, which is why it is the only 403 of the wiki — a member sees the project, but does not get to erase what it learned.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "description": "Wiki page id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only a company admin can delete a wiki page.", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/wiki/{pageId}/move": { "patch": { "operationId": "moveProjectWikiPage", "summary": "Re-file a wiki page in the table of contents", "description": "Sets the page's parent and its rank among its new siblings. `parentId: null` brings it back to the root. A page cannot be filed under itself or under one of its own sub-pages — the branch would disappear from the summary.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "description": "Wiki page id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parentId", "position" ], "properties": { "parentId": { "type": "string", "format": "uuid", "nullable": true }, "position": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Rank among the new siblings; past the end of the list it lands last." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/ProjectWikiPageDetail" } }, "required": [ "page" ] } } } }, "400": { "description": "Validation error, malformed id, an unknown parent page, or a move that would put the page under itself.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/projects/{projectId}/wiki/{pageId}/revisions": { "get": { "operationId": "listProjectWikiRevisions", "summary": "Page through a wiki page's history", "description": "Newest first. Each entry carries the page's full text at that moment, which is why the page size is capped hard: an often-edited page would otherwise answer in megabytes.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "description": "Wiki page id", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectWikiRevision" } }, "total": { "type": "integer", "description": "Revisions the page has in all, ignoring limit/offset." }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "revisions", "total", "limit", "offset" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/projects/{projectId}/wiki/{pageId}/revisions/{revisionId}": { "get": { "operationId": "getProjectWikiRevisionContent", "summary": "Read one revision's full text", "description": "On demand only (perf(projects-cron), PLAN-perf.md E3) — what GET /projects/{id} and GET /projects/{id}/wiki/{pageId} no longer carry per revision (see ProjectWikiRevisionSummary). Same 404-not-403 rule as the rest of the wiki.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "description": "Wiki page id", "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionId", "in": "path", "required": true, "description": "Revision id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "$ref": "#/components/schemas/ProjectWikiRevisionContent" } }, "required": [ "revision" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown page, or a revision that does not belong to this page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/projects/{projectId}/wiki/{pageId}/revisions/{revisionId}/restore": { "post": { "operationId": "restoreProjectWikiRevision", "summary": "Go back to an earlier version of a page", "description": "Nothing is erased: restoring ADDS a revision whose content is the old one, so the history of a page never gets shorter. The body is optional — restoring without a word is legitimate, and the default message names the restored `sha`.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project id", "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "description": "Wiki page id", "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionId", "in": "path", "required": true, "description": "Revision id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Optional.", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/ProjectWikiPageDetail" } }, "required": [ "page" ] } } } }, "400": { "description": "Malformed project/card/page/revision id, invalid JSON body, or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown page, or a revision that does not belong to this page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/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/integrations/catalog": { "get": { "operationId": "publicListIntegrationCatalog", "summary": "List available/coming-soon connectors, without a session", "description": "Same catalog as `GET /integrations/catalog`. Read by the vitrine demo. Cached 5 min, public per-IP rate limit.", "tags": [ "Public" ], "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" } } } } } }, "security": [] } }, "/public/invitations/{token}": { "get": { "operationId": "publicPreviewInvitation", "summary": "Preview a company invitation", "description": "Used by the accept-invite page. Own per-IP rate limit (60/min); a 429 carries Retry-After.", "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-preferences/unsubscribe": { "get": { "operationId": "publicUnsubscribePage", "summary": "Unsubscribe from an optional-email family (the link in the footer)", "description": "Opened by a person, from their inbox, so it answers with an HTML page rather than JSON — rendered in the recipient's own locale. The token is an HMAC over `userId:family` minted into the email itself — no session, nothing to enumerate, and no expiry, because an unsubscribe link in a two-year-old email must still work. Applies to the three OPTIONAL families only; essential email (sign-in codes, receipts, security alerts, terms updates) has no opt-out. Every write merges, so unsubscribing from one family never resubscribes another.", "tags": [ "Public" ], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTML confirmation page.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid or tampered token — HTML page saying so.", "content": { "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "too_many_requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "post": { "operationId": "publicUnsubscribeOneClick", "summary": "RFC 8058 one-click unsubscribe", "description": "What Gmail's and Outlook's own unsubscribe buttons call, from the `List-Unsubscribe` header the optional emails carry. Same token and same effect as the GET. The token is an HMAC over `userId:family` minted into the email itself — no session, nothing to enumerate, and no expiry, because an unsubscribe link in a two-year-old email must still work. Applies to the three OPTIONAL families only; essential email (sign-in codes, receipts, security alerts, terms updates) has no opt-out. Every write merges, so unsubscribing from one family never resubscribes another.", "tags": [ "Public" ], "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Query is the advertised form; a form-encoded body is also accepted." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid or tampered token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "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": [] } }, "/roadmap": { "get": { "operationId": "listRoadmap", "summary": "La roadmap publiée", "description": "Sans pagination — la roadmap se lit d'un bloc. Triée par `position`, puis par ancienneté à rang égal.", "tags": [ "Marketing Content" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoadmapEntry" } } } } } }, "security": [] } }, "/changelog": { "get": { "operationId": "listChangelog", "summary": "Les livraisons publiées", "description": "Triées sur `releasedAt` (la date de livraison), la plus récente en premier.", "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 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChangelogEntry" } } } } } }, "security": [] } }, "/changelog/{slug}": { "get": { "operationId": "getChangelogEntry", "summary": "Une entrée de changelog publiée", "tags": [ "Marketing Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Entry slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangelogEntry" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/press": { "get": { "operationId": "listPressReleases", "summary": "Les communiqués de presse publiés", "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/PressRelease" } } } } } }, "security": [] } }, "/press/{slug}": { "get": { "operationId": "getPressRelease", "summary": "Un communiqué de presse publié", "tags": [ "Marketing Content" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Release slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PressRelease" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/site-banners": { "get": { "operationId": "listSiteBanners", "summary": "Les bandeaux à l'antenne pour une surface", "description": "Ni brouillon, ni prévu, ni passé : la fenêtre d'affichage est appliquée côté serveur. `surface` est obligatoire — `both` est une AUDIENCE, jamais une question.", "tags": [ "Marketing Content" ], "parameters": [ { "name": "surface", "in": "query", "required": true, "description": "", "schema": { "type": "string", "enum": [ "marketing", "app" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteBanner" } } } } }, "400": { "description": "Unknown surface", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/notices": { "get": { "operationId": "listNotices", "summary": "Questions your agents are waiting on you for, or your settled history", "description": "Two sorts, never mixed on the same page. The default — `state=open` (or omitted), no `order` — is the queue sorted the way the Floor shows it: priority descending, then kind rank (blocker, guardrail, choice, info), then oldest first; a plain `limit`, `nextCursor` always `null` (AF-52: this order is fixed, never paginated). Any other `state` (`answered`, `expired`, `withdrawn`, `settled`, `all`), or `order=recent` on `open`, switches to the HISTORY sort instead: most recently settled first (answered date if answered, else created date), paginated by the opaque `cursor` — pass back a page's `nextCursor` as the next call's `cursor` until it comes back `null`. `settled` means any of the three non-open states at once (answered, expired or withdrawn) — use it for a history view that must never show a still-open notice; `all` keeps open notices mixed in, for a combined per-person journal.\n\nA company admin may read a colleague's queue/history with `recipientUserId`, or the whole company's, line by line, with `scope=company` (the two are mutually exclusive) — anyone else passing either gets 403, never a silently empty list. Notices past their `expiresAt` flip to `expired` on read, so this list never shows a stale question.", "tags": [ "Notices" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "open", "answered", "expired", "withdrawn", "settled", "all" ], "default": "open" } }, { "name": "kind", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "blocker", "guardrail", "choice", "info" ] } }, { "name": "priority", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "critical", "high", "normal", "low" ] } }, { "name": "agentId", "in": "query", "required": false, "description": "Only this agent's notices.", "schema": { "type": "string", "format": "uuid" } }, { "name": "conversationId", "in": "query", "required": false, "description": "Only notices raised from this chat session — what a session thread asks for so it shows its own questions and not the agent's others.", "schema": { "type": "string", "format": "uuid" } }, { "name": "originKind", "in": "query", "required": false, "description": "Only notices raised from this kind of work.", "schema": { "type": "string", "enum": [ "chat", "cron", "email", "webhook", "interagent", "subagent" ] } }, { "name": "recipientUserId", "in": "query", "required": false, "description": "Company admins only — read a colleague's queue/history instead of your own. Mutually exclusive with `scope=company`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "scope", "in": "query", "required": false, "description": "Company admins only — `company` reads every notice of the company (history sort applies) instead of one recipient. Mutually exclusive with `recipientUserId`.", "schema": { "type": "string", "enum": [ "mine", "company" ] } }, { "name": "order", "in": "query", "required": false, "description": "Force the history sort (most recently settled first) even when `state=open`.", "schema": { "type": "string", "enum": [ "recent" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous page's `nextCursor` — only meaningful on the history sort.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoticeList" } } } }, "400": { "description": "Invalid query parameters, or an invalid cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`recipientUserId`/`scope=company` given by a non-admin, or for a user outside your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "You belong to no company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/notices/count": { "get": { "operationId": "countNotices", "summary": "Badge counters for your open notices", "description": "Cheap counter behind the chrome badge. `blocking` counts everything but `info` — the notices that actually stop an agent.", "tags": [ "Notices" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoticeCount" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/notices/{id}": { "get": { "operationId": "getNotice", "summary": "Get one notice", "description": "Readable by its recipient, or by an admin of the company the notice belongs to.", "tags": [ "Notices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Notice id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "notice": { "$ref": "#/components/schemas/Notice" } }, "required": [ "notice" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" } }, "/notices/{id}/respond": { "post": { "operationId": "respondToNotice", "summary": "Answer a notice", "description": "The recipient, or an admin of the notice's company, picks one of the notice's `options`. Answering is one-shot: a second call gets 409 NOTICE_NOT_OPEN rather than overwriting the first decision. Answering a `guardrail` with `always` makes the permission standing — the same agent asking the same subject again is answered instantly, with no new notice.", "tags": [ "Notices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Notice id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RespondNoticeRequest" } } } }, "responses": { "200": { "description": "The answered notice, with its `answer` filled in.", "content": { "application/json": { "schema": { "type": "object", "properties": { "notice": { "$ref": "#/components/schemas/Notice" } }, "required": [ "notice" ] } } } }, "400": { "description": "INVALID_INPUT / UNKNOWN_OPTION / TEXT_REQUIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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" } } } }, "409": { "description": "NOTICE_NOT_OPEN — already answered, expired or withdrawn.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/notifications": { "get": { "operationId": "listNotifications", "summary": "List your notifications", "description": "Newest first. Cursor pagination: pass the last item's `timestamp` as `before` (and its `id` as `beforeId`).", "tags": [ "Notifications" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer" } }, { "name": "before", "in": "query", "required": false, "description": "Only notifications strictly older than this instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "beforeId", "in": "query", "required": false, "description": "Tiebreak for `before`.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } } } } }, "400": { "description": "INVALID_LIMIT / INVALID_BEFORE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/notifications/unread-count": { "get": { "operationId": "countUnreadNotifications", "summary": "Count unread notifications", "tags": [ "Notifications" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" } }, "required": [ "count" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/notifications/read-all": { "patch": { "operationId": "markAllNotificationsRead", "summary": "Mark every notification read", "tags": [ "Notifications" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/notifications/{id}/read": { "patch": { "operationId": "markNotificationRead", "summary": "Mark one notification read", "description": "A no-op (still 200) on a notification that is not yours.", "tags": [ "Notifications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Notification id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/notifications/{id}/unread": { "patch": { "operationId": "markNotificationUnread", "summary": "Mark one notification unread", "tags": [ "Notifications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Notification id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/notifications/sse": { "get": { "operationId": "streamNotifications", "summary": "SSE stream of your notifications and live agent events", "description": "Not a JSON response: `Content-Type: text/event-stream`, authenticated with the same Bearer header (an `aik_` key works). Events: `notification` (data = a Notification), and live events of the agents you can see — `agent_status`, `shared_item`, `tool_log`, `cron_jobs_updated`, `notice_created`, `notice_answered`, `email_message`, `webhook_event`, `interagent_message` — whose data is `{ agentId, ... }` — and `project_cards_changed` (data = `{ projectId }`) for a board write in any project of your company. Kept alive with `: ping` comments every 25 s.", "tags": [ "Notifications" ], "responses": { "200": { "description": "text/event-stream — see description for the event names.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/agents/{agentId}/shared": { "get": { "operationId": "listAgentSharedItems", "summary": "List documents and secrets shared with an agent", "description": "List view: `value` is omitted.", "tags": [ "Agent Shared Items" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSharedItem" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "createAgentSharedItem", "summary": "Share a document or a secret with an agent", "tags": [ "Agent Shared Items" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "name", "value" ], "properties": { "type": { "type": "string", "enum": [ "document", "secret" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "mimeType": { "type": "string" }, "fileSize": { "type": "integer" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSharedItem" } } } }, "400": { "description": "type, name, value required / invalid type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/shared/{itemId}": { "get": { "operationId": "getAgentSharedItem", "summary": "Get a shared item, value included", "tags": [ "Agent Shared Items" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "description": "Shared item id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSharedItem" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "read" }, "delete": { "operationId": "deleteAgentSharedItem", "summary": "Delete a shared item you uploaded", "tags": [ "Agent Shared Items" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "description": "Shared item id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "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": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/email": { "get": { "operationId": "getAgentEmail", "summary": "Get an agent's email address and settings", "description": "`email` is null until the channel is enabled for this agent.", "tags": [ "Agent Email" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "planAllowed": { "type": "boolean" }, "channelEnabled": { "type": "boolean" }, "email": { "$ref": "#/components/schemas/AgentEmailSettings", "nullable": true } }, "required": [ "planAllowed", "channelEnabled", "email" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_EMAIL_DISABLED / EMAIL_COLD_SEND_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / EMAIL_NOT_ENABLED / THREAD_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "EMAIL_ALREADY_ENABLED / ALREADY_PROCESSED / EMAIL_SUPPRESSED / THREAD_FROZEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "enableAgentEmail", "summary": "Give an agent its own email address", "description": "Owner or company admin; the agent engine must support email.", "tags": [ "Agent Email" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/AgentEmailSettings" } }, "required": [ "email" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_EMAIL_DISABLED / EMAIL_COLD_SEND_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / EMAIL_NOT_ENABLED / THREAD_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "EMAIL_ALREADY_ENABLED / ALREADY_PROCESSED / EMAIL_SUPPRESSED / THREAD_FROZEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" }, "patch": { "operationId": "updateAgentEmail", "summary": "Update an agent's email settings", "tags": [ "Agent Email" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "senderPolicy": { "type": "string", "enum": [ "open", "allowlist" ] }, "coldSendMode": { "type": "string", "enum": [ "approval", "auto", "disabled" ] }, "allowlist": { "type": "array", "maxItems": 200, "items": { "type": "string", "maxLength": 320 } }, "denylist": { "type": "array", "maxItems": 200, "items": { "type": "string", "maxLength": 320 } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/AgentEmailSettings" } }, "required": [ "email" ] } } } }, "400": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_EMAIL_DISABLED / EMAIL_COLD_SEND_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / EMAIL_NOT_ENABLED / THREAD_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "EMAIL_ALREADY_ENABLED / ALREADY_PROCESSED / EMAIL_SUPPRESSED / THREAD_FROZEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "disableAgentEmail", "summary": "Disable an agent's email address", "tags": [ "Agent Email" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_EMAIL_DISABLED / EMAIL_COLD_SEND_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / EMAIL_NOT_ENABLED / THREAD_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "EMAIL_ALREADY_ENABLED / ALREADY_PROCESSED / EMAIL_SUPPRESSED / THREAD_FROZEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/email/threads": { "get": { "operationId": "listAgentEmailThreads", "summary": "List an agent's email threads", "tags": [ "Agent Email" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/AgentEmailThread" } } }, "required": [ "threads" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_EMAIL_DISABLED / EMAIL_COLD_SEND_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / EMAIL_NOT_ENABLED / THREAD_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "EMAIL_ALREADY_ENABLED / ALREADY_PROCESSED / EMAIL_SUPPRESSED / THREAD_FROZEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/agents/{agentId}/email/threads/{threadId}": { "get": { "operationId": "getAgentEmailThread", "summary": "Get an email thread with its messages", "description": "Also marks the thread read for the caller.", "tags": [ "Agent Email" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "threadId", "in": "path", "required": true, "description": "Thread id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "thread": { "$ref": "#/components/schemas/AgentEmailThread" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/AgentEmailMessage" } } }, "required": [ "thread", "messages" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_EMAIL_DISABLED / EMAIL_COLD_SEND_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / EMAIL_NOT_ENABLED / THREAD_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "EMAIL_ALREADY_ENABLED / ALREADY_PROCESSED / EMAIL_SUPPRESSED / THREAD_FROZEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/agents/{agentId}/email/threads/{threadId}/unfreeze": { "post": { "operationId": "unfreezeAgentEmailThread", "summary": "Unfreeze an email thread frozen by the anti-loop guard", "description": "Agent owner or company admin only. Sets the thread back to `active`, resets its automatic-exchange counters and, when the latest inbound message was a human one skipped by the freeze, queues it again for the agent (`redelivered: true`).", "tags": [ "Agent Email" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "threadId", "in": "path", "required": true, "description": "Thread id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "thread": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active" ] } }, "required": [ "id", "status" ] }, "redelivered": { "type": "boolean" } }, "required": [ "thread", "redelivered" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_EMAIL_DISABLED / EMAIL_COLD_SEND_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / EMAIL_NOT_ENABLED / THREAD_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "THREAD_NOT_FROZEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/email/outbound/{messageId}/approve": { "post": { "operationId": "approveAgentOutboundEmail", "summary": "Approve an email waiting for approval", "tags": [ "Agent Email" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "messageId", "in": "path", "required": true, "description": "Pending message id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/AgentEmailMessage" } }, "required": [ "message" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_EMAIL_DISABLED / EMAIL_COLD_SEND_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / EMAIL_NOT_ENABLED / THREAD_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "EMAIL_ALREADY_ENABLED / ALREADY_PROCESSED / EMAIL_SUPPRESSED / THREAD_FROZEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "EMAIL_QUOTA_EXCEEDED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/email/outbound/{messageId}/reject": { "post": { "operationId": "rejectAgentOutboundEmail", "summary": "Reject an email waiting for approval", "tags": [ "Agent Email" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "messageId", "in": "path", "required": true, "description": "Pending message id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/AgentEmailMessage" } }, "required": [ "message" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_EMAIL_DISABLED / EMAIL_COLD_SEND_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / EMAIL_NOT_ENABLED / THREAD_NOT_FOUND / MESSAGE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "EMAIL_ALREADY_ENABLED / ALREADY_PROCESSED / EMAIL_SUPPRESSED / THREAD_FROZEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/webhooks": { "get": { "operationId": "listAgentWebhooks", "summary": "List an agent's inbound webhook endpoints", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "planAllowed": { "type": "boolean" }, "channelEnabled": { "type": "boolean" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/AgentWebhookEndpoint" } } }, "required": [ "endpoints" ] } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "createAgentWebhook", "summary": "Create an inbound webhook endpoint", "description": "Returns the endpoint URL and its token ONCE. Every provider but `none` requires `verificationSecret`.", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "provider": { "type": "string", "enum": [ "none", "shared_secret", "hmac_generic", "standard_webhooks", "stripe", "github" ], "default": "none" }, "verificationSecret": { "type": "string", "minLength": 8, "maxLength": 512 }, "signatureConfig": { "type": "object", "additionalProperties": true }, "filters": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/WebhookFilter" } }, "maxPayloadBytes": { "type": "integer", "nullable": true, "minimum": 1024, "maximum": 5242880 }, "rateLimitPerMinute": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 600 }, "dailyTurnQuota": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 10000 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/AgentWebhookEndpoint" }, "url": { "type": "string" }, "token": { "type": "string" } }, "required": [ "endpoint", "url", "token" ] } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/webhooks/{endpointId}": { "get": { "operationId": "getAgentWebhook", "summary": "Get a webhook endpoint", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "endpointId", "in": "path", "required": true, "description": "Webhook endpoint id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/AgentWebhookEndpoint" } }, "required": [ "endpoint" ] } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "patch": { "operationId": "updateAgentWebhook", "summary": "Update a webhook endpoint", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "endpointId", "in": "path", "required": true, "description": "Webhook endpoint id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "filters": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/WebhookFilter" } }, "signatureConfig": { "type": "object", "additionalProperties": true }, "maxPayloadBytes": { "type": "integer", "nullable": true }, "rateLimitPerMinute": { "type": "integer", "nullable": true }, "dailyTurnQuota": { "type": "integer", "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/AgentWebhookEndpoint" } }, "required": [ "endpoint" ] } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "deleteAgentWebhook", "summary": "Delete a webhook endpoint", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "endpointId", "in": "path", "required": true, "description": "Webhook endpoint id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/webhooks/{endpointId}/rotate": { "post": { "operationId": "rotateAgentWebhook", "summary": "Rotate the URL token and/or the verification secret", "description": "`url` and `token` are returned only when `rotateToken` is true.", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "endpointId", "in": "path", "required": true, "description": "Webhook endpoint id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "At least one of the two.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rotateToken": { "type": "boolean" }, "verificationSecret": { "type": "string", "minLength": 8, "maxLength": 512 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/AgentWebhookEndpoint" }, "url": { "type": "string" }, "token": { "type": "string" } }, "required": [ "endpoint" ] } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/webhooks/{endpointId}/test": { "post": { "operationId": "testAgentWebhook", "summary": "Run a test payload through the endpoint pipeline", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "endpointId", "in": "path", "required": true, "description": "Webhook endpoint id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "string", "maxLength": 65536 }, "contentType": { "type": "string", "maxLength": 120 }, "deliver": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "`outcome.outcome` is one of delivered, pending_agent, deduped, paused, skipped, quarantined, endpoint_inactive, payload_too_large, invalid_signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/agents/{agentId}/webhooks/{endpointId}/events": { "get": { "operationId": "listAgentWebhookEvents", "summary": "List events received by a webhook endpoint", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "endpointId", "in": "path", "required": true, "description": "Webhook endpoint id", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "pending_agent", "delivered", "skipped", "quarantined" ] } }, { "name": "before", "in": "query", "required": false, "description": "Only events older than this instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AgentWebhookEvent" } } }, "required": [ "events" ] } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/agents/{agentId}/webhooks/{endpointId}/events/{eventId}": { "get": { "operationId": "getAgentWebhookEvent", "summary": "Get one webhook event with its raw payload and (redacted) headers", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "endpointId", "in": "path", "required": true, "description": "Webhook endpoint id", "schema": { "type": "string", "format": "uuid" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "allOf": [ { "$ref": "#/components/schemas/AgentWebhookEvent" }, { "type": "object", "properties": { "receivedHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "queryParams": { "type": "object", "additionalProperties": { "type": "string" } }, "rawPayload": { "type": "string" }, "processingNote": { "type": "string", "nullable": true } } } ] } }, "required": [ "event" ] } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/agents/{agentId}/webhooks/{endpointId}/events/{eventId}/requeue": { "post": { "operationId": "requeueAgentWebhookEvent", "summary": "Deliver a skipped or quarantined event to the agent again", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "endpointId", "in": "path", "required": true, "description": "Webhook endpoint id", "schema": { "type": "string", "format": "uuid" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "VALIDATION_FAILED / PROVIDER_NOT_AVAILABLE / PROVIDER_HAS_NO_SECRET / EVENT_NOT_REQUEUEABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN / PLAN_WEBHOOK_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND / ENDPOINT_NOT_FOUND / EVENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/wh/{token}": { "get": { "operationId": "probeWebhookEndpoint", "summary": "Probe a webhook endpoint URL (HEAD/GET, nothing is ingested)", "description": "Some providers probe the callback URL before registering it. Empty body.", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The endpoint token, from the `url` of the endpoint (`/wh/`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The endpoint is live." }, "404": { "description": "Unknown token." }, "410": { "description": "Endpoint disabled, agent inactive, channel off or plan not eligible." } }, "security": [] }, "post": { "operationId": "receiveWebhookEvent", "summary": "Send an event to an agent webhook endpoint", "description": "The body is read raw and verified with the endpoint signature scheme (none, shared secret, generic HMAC, Standard Webhooks, Stripe, GitHub, custom). Transient outcomes (duplicate, filtered, rate-limited, over quota, paused) still answer 200 with the stored status, so providers do not retry into the limits.", "tags": [ "Agent Webhooks" ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The endpoint token, from the `url` of the endpoint (`/wh/`).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "`status` is delivered, pending_agent, deduped, skipped or quarantined; `reason` is set for skipped/quarantined.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "eventId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "delivered", "pending_agent", "deduped", "skipped", "quarantined" ] }, "reason": { "type": "string" } }, "required": [ "ok" ] } } } }, "401": { "description": "INVALID_SIGNATURE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "UNKNOWN_ENDPOINT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "ENDPOINT_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests from this IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/company/dashboard/overview": { "get": { "operationId": "getDashboardOverview", "summary": "The whole dashboard in one call", "description": "Company admins only. Inference calls and tokens (Atako vs BYOK), activity by trigger, integration logs, mail, webhooks, relay, schedules, agent versions and notices over the window.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "grain", "in": "query", "required": false, "description": "Bucket size.", "schema": { "type": "string", "enum": [ "hour", "day", "quarter" ], "default": "day" } }, { "name": "from", "in": "query", "required": false, "description": "Start day (YYYY-MM-DD) — or `since`/`until`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "since", "in": "query", "required": false, "description": "Start instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "description": "End instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA time zone (default UTC).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "`buckets` are epoch-ms bucket starts; every `series` is positional on `buckets`.", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "grain": { "type": "string" }, "tz": { "type": "string" }, "buckets": { "type": "array", "items": { "type": "number" } }, "now": { "type": "number" }, "inference": { "type": "object", "additionalProperties": true }, "activity": { "type": "object", "additionalProperties": true }, "logs": { "type": "object", "additionalProperties": true }, "usage": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "mail": { "type": "object", "additionalProperties": true }, "webhooks": { "type": "object", "additionalProperties": true }, "relay": { "type": "object", "additionalProperties": true }, "schedule": { "type": "object", "additionalProperties": true }, "versions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "notices": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid grain/from/to/since/until, or too many buckets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/credits": { "get": { "operationId": "getDashboardCredits", "summary": "Credit balance and consumption", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "range", "in": "query", "required": false, "description": "Preset window — or `from`/`to`.", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" } }, { "name": "from", "in": "query", "required": false, "description": "Start day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA time zone for day boundaries (default UTC).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "object", "additionalProperties": true }, "transactions": { "type": "object", "additionalProperties": true }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tokenSeries": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "split": { "type": "object", "properties": { "atako": { "type": "number" }, "byok": { "type": "number" } } } }, "additionalProperties": true } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/byok": { "get": { "operationId": "getDashboardByok", "summary": "Token volumes on your own LLM keys", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "range", "in": "query", "required": false, "description": "Preset window — or `from`/`to`.", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" } }, { "name": "from", "in": "query", "required": false, "description": "Start day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA time zone for day boundaries (default UTC).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "providers": { "type": "array", "items": { "type": "string" } }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "totals": { "type": "object", "additionalProperties": true }, "byProvider": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/integration-logs": { "get": { "operationId": "listDashboardIntegrationLogs", "summary": "Integration call journal", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "teamId", "in": "query", "required": false, "description": "Filter by team.", "schema": { "type": "string", "format": "uuid" } }, { "name": "agentId", "in": "query", "required": false, "description": "Filter by agent.", "schema": { "type": "string", "format": "uuid" } }, { "name": "providerKey", "in": "query", "required": false, "description": "Filter by connector, e.g. \"github\".", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start day.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End day.", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "required": false, "description": "Page.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/integration-logs/export": { "get": { "operationId": "exportDashboardIntegrationLogs", "summary": "Integration call journal as CSV", "description": "Company admins only. Same filters as the list, without paging (capped).", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "teamId", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "agentId", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "providerKey", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "CSV attachment.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/agents/{agentId}/activity": { "get": { "operationId": "getDashboardAgentActivity", "summary": "One agent's activity events", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } }, { "name": "originKind", "in": "query", "required": false, "description": "Filter by trigger.", "schema": { "type": "string" } }, { "name": "range", "in": "query", "required": false, "description": "Days.", "schema": { "type": "integer", "enum": [ 7, 14, 30 ], "default": 7 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "additionalProperties": true }, "from": { "type": "string" }, "to": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/agents/{agentId}/upgrade": { "post": { "operationId": "upgradeDashboardAgent", "summary": "Upgrade an agent to a newer engine version", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "engineVersion": { "type": "string" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Agent is completed / Unknown release tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_MACHINE_LOST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Dispatch failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/company/dashboard/integrations-usage": { "get": { "operationId": "getDashboardIntegrationsUsage", "summary": "Calls per connector", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "range", "in": "query", "required": false, "description": "Preset window — or `from`/`to`.", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" } }, { "name": "from", "in": "query", "required": false, "description": "Start day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA time zone for day boundaries (default UTC).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "array", "items": { "type": "object", "properties": { "providerKey": { "type": "string" }, "providerName": { "type": "string" }, "providerLogo": { "type": "string", "nullable": true }, "callCount": { "type": "integer" }, "distinctAgents": { "type": "integer" }, "lastCallAt": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/storage": { "get": { "operationId": "getDashboardStorage", "summary": "Context storage usage", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalBytes": { "type": "integer" }, "fileCount": { "type": "integer" } }, "required": [ "totalBytes", "fileCount" ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/storage/export": { "get": { "operationId": "exportDashboardStorage", "summary": "Download the company Context as a zip", "description": "Company admins only. Refused (413) above 200 files or 100 MiB.", "tags": [ "Company Dashboard" ], "responses": { "200": { "description": "Zip attachment.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too large to export.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/cron-jobs": { "get": { "operationId": "listDashboardCronJobs", "summary": "Scheduled tasks across the company", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "tz", "in": "query", "required": false, "description": "Time zone of the hourly histogram.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "histogram": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/agent-versions": { "get": { "operationId": "listDashboardAgentVersions", "summary": "Engine version and upgrade status of every agent", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/mail": { "get": { "operationId": "getDashboardMail", "summary": "Agent mailboxes activity", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "grain", "in": "query", "required": false, "description": "Bucket size.", "schema": { "type": "string", "enum": [ "hour", "day", "quarter" ], "default": "day" } }, { "name": "from", "in": "query", "required": false, "description": "Start day (YYYY-MM-DD) — or `since`/`until`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "since", "in": "query", "required": false, "description": "Start instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "description": "End instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA time zone (default UTC).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "`buckets` are epoch-ms bucket starts; every `series` is positional on `buckets`.", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "grain": { "type": "string" }, "tz": { "type": "string" }, "buckets": { "type": "array", "items": { "type": "number" } }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "mailboxes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "totals": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/webhooks": { "get": { "operationId": "getDashboardWebhooks", "summary": "Inbound webhook activity", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "grain", "in": "query", "required": false, "description": "Bucket size.", "schema": { "type": "string", "enum": [ "hour", "day", "quarter" ], "default": "day" } }, { "name": "from", "in": "query", "required": false, "description": "Start day (YYYY-MM-DD) — or `since`/`until`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "since", "in": "query", "required": false, "description": "Start instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "description": "End instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA time zone (default UTC).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "`buckets` are epoch-ms bucket starts; every `series` is positional on `buckets`.", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "grain": { "type": "string" }, "tz": { "type": "string" }, "buckets": { "type": "array", "items": { "type": "number" } }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "services": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "byHour": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "totals": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/relay": { "get": { "operationId": "getDashboardRelay", "summary": "Agent-to-agent relay graph", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "grain", "in": "query", "required": false, "description": "Bucket size.", "schema": { "type": "string", "enum": [ "hour", "day", "quarter" ], "default": "day" } }, { "name": "from", "in": "query", "required": false, "description": "Start day (YYYY-MM-DD) — or `since`/`until`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "since", "in": "query", "required": false, "description": "Start instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "description": "End instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA time zone (default UTC).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "`buckets` are epoch-ms bucket starts; every `series` is positional on `buckets`.", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "grain": { "type": "string" }, "tz": { "type": "string" }, "buckets": { "type": "array", "items": { "type": "number" } }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nodes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "edges": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "peak": { "type": "number" }, "messages": { "type": "number" }, "members": { "type": "number" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/dashboard/notices": { "get": { "operationId": "getDashboardNotices", "summary": "Notices raised vs answered", "description": "Company admins only.", "tags": [ "Company Dashboard" ], "parameters": [ { "name": "range", "in": "query", "required": false, "description": "Preset window — or `from`/`to`.", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" } }, { "name": "from", "in": "query", "required": false, "description": "Start day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA time zone for day boundaries (default UTC).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "tz": { "type": "string" }, "buckets": { "type": "array", "items": { "type": "number" } }, "totals": { "type": "object", "additionalProperties": true }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "now": { "type": "number" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No company found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } }, "/company/llm-keys": { "get": { "operationId": "listLlmProviderKeys", "summary": "List your company's LLM keys", "description": "Company admins only.", "tags": [ "LLM Provider Keys" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LlmProviderKey" } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin, or BYOK_NOT_ALLOWED for this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found — or bring-your-own-key is not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" }, "post": { "operationId": "createLlmProviderKey", "summary": "Add an LLM key (validated right away)", "description": "Company admins only. The secret is stored encrypted and never returned.", "tags": [ "LLM Provider Keys" ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "label", "secret" ], "properties": { "provider": { "type": "string", "enum": [ "openrouter", "openai", "anthropic" ] }, "label": { "type": "string", "minLength": 1 }, "secret": { "type": "string", "minLength": 1 }, "config": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/LlmProviderKey" }, { "type": "object", "properties": { "validationMessage": { "type": "string", "nullable": true } } } ] } } } }, "400": { "description": "provider/label/secret required, PROVIDER_NOT_SUPPORTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin, or BYOK_NOT_ALLOWED for this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found — or bring-your-own-key is not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/company/llm-keys/{id}": { "patch": { "operationId": "updateLlmProviderKey", "summary": "Update an LLM key", "description": "Company admins only.", "tags": [ "LLM Provider Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Key id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_validation", "active", "invalid", "disabled" ] }, "priority": { "type": "integer" }, "config": { "type": "object", "additionalProperties": true }, "isDefaultForCompany": { "type": "boolean" }, "monthlyCapUsd": { "type": "number", "nullable": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmProviderKey" } } } }, "400": { "description": "Invalid status / INVALID_MONTHLY_CAP / LABEL_REQUIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin, or BYOK_NOT_ALLOWED for this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found — or bring-your-own-key is not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" }, "delete": { "operationId": "deleteLlmProviderKey", "summary": "Delete an LLM key", "description": "Company admins only. Refused (409) while agents still use it.", "tags": [ "LLM Provider Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Key id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin, or BYOK_NOT_ALLOWED for this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found — or bring-your-own-key is not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "KEY_IN_USE", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/company/llm-keys/{id}/test": { "post": { "operationId": "testLlmProviderKey", "summary": "Re-validate an LLM key", "description": "Company admins only.", "tags": [ "LLM Provider Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Key id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/LlmProviderKey" }, { "type": "object", "properties": { "validationMessage": { "type": "string", "nullable": true } } } ] } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin, or BYOK_NOT_ALLOWED for this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found — or bring-your-own-key is not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "write" } }, "/company/llm-keys/{id}/usage": { "get": { "operationId": "getLlmProviderKeyUsage", "summary": "Usage of an LLM key", "description": "Company admins only. `costUsd` is what YOUR provider billed you on your own key — not an Atako price.", "tags": [ "LLM Provider Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Key id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "currentMonth": { "type": "object", "properties": { "requestCount": { "type": "integer" }, "promptTokens": { "type": "integer" }, "completionTokens": { "type": "integer" }, "cachedTokens": { "type": "integer" }, "costUsd": { "type": "number" } } }, "last30Days": { "type": "object", "properties": { "requestCount": { "type": "integer" }, "promptTokens": { "type": "integer" }, "completionTokens": { "type": "integer" }, "cachedTokens": { "type": "integer" }, "costUsd": { "type": "number" } } } } } } } }, "401": { "description": "Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company admin, or BYOK_NOT_ALLOWED for this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found — or bring-your-own-key is not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-atako-api-key": "read" } } } }