> ## Documentation Index > Fetch the complete documentation index at: https://docs.atako.ai/llms.txt > Use this file to discover all available pages before exploring further. # Launch a draft: create the agent it describes > Replays the draft through agent creation: same `canCreateAgents`, subscription and licence checks and error codes as `POST /agents`. The launcher owns the agent. Every connection and planned integration is resolved BEFORE anything is created; `integrationMapping` maps a planned integration slug to a connection (without it, a slug resolves when exactly one connection of that provider is visible). 200 with the existing agent when the draft was already launched. Grants or file grants that fail come back in `warnings` without cancelling the agent. ## OpenAPI ````yaml /api-reference/openapi.json post /agent-drafts/{id}/launch 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. ## Authentication Every non-public endpoint takes a Bearer token that is either: - a **programmatic API key** (`aik_…`) — create one at [app.atako.ai](https://app.atako.ai) → Settings → API keys (company-admin only), or - a **Supabase session JWT** — what the web app itself sends; not practical to obtain outside a browser session. ```bash curl https://api.atako.ai/agents -H "Authorization: Bearer aik_..." ``` An API key acts as its owning user, within the limits of the key: - **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. - **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. - **Expiry** — optional (30, 90 or 365 days); an expired key gets `401 API_KEY_EXPIRED`. Each operation carries `x-atako-api-key: read | write | forbidden` — the minimum key scope it needs, or `forbidden`. ## Live events `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. ## Uploading a file Two 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`. ## Other Atako HTTP surfaces (not covered by this spec) - **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). - **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. ## Errors Errors 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. ## Rate limits Authenticated routes: 6000 requests/min per user (`authRateLimit`). Public GET routes: 60/min per IP. A handful of sensitive public POST routes (newsletter signup, signup email check, invitation preview) are limited to 10 requests / 15 min per IP. ## Pagination List 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 security: [] 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 paths: /agent-drafts/{id}/launch: post: tags: - Agent drafts summary: 'Launch a draft: create the agent it describes' description: >- Replays the draft through agent creation: same `canCreateAgents`, subscription and licence checks and error codes as `POST /agents`. The launcher owns the agent. Every connection and planned integration is resolved BEFORE anything is created; `integrationMapping` maps a planned integration slug to a connection (without it, a slug resolves when exactly one connection of that provider is visible). 200 with the existing agent when the draft was already launched. Grants or file grants that fail come back in `warnings` without cancelling the agent. operationId: launchAgentDraft parameters: - name: id in: path required: true description: Draft id schema: type: string format: uuid requestBody: description: '' required: true content: application/json: schema: type: object properties: integrationMapping: type: object additionalProperties: type: string format: uuid responses: '200': description: Already launched content: application/json: schema: type: object required: - agent - draft - warnings properties: agent: $ref: '#/components/schemas/Agent' draft: $ref: '#/components/schemas/AgentDraft' warnings: type: array items: type: object additionalProperties: true '201': description: '' content: application/json: schema: type: object required: - agent - draft - warnings properties: agent: $ref: '#/components/schemas/Agent' draft: $ref: '#/components/schemas/AgentDraft' warnings: type: array items: type: object additionalProperties: true '400': description: Validation error / createAgent prerequisite 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 / AGENT_LIMIT_REACHED / NOT_TEAM_MEMBER content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found, or the caller is not authorized to access this resource. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: DRAFT_LAUNCH_IN_PROGRESS content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- DRAFT_CONNECTION_GONE (connectionIds) / DRAFT_INTEGRATION_UNRESOLVED (slugs) content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: 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 AgentDraft: type: object description: >- Agent en préparation. Jamais une ligne `agents` : aucune VM, licence ni bucket. properties: id: type: string format: uuid companyId: type: string format: uuid teamId: type: string format: uuid nullable: true description: >- Host team, or null for an individual agent (a company with no team yet). createdByUserId: type: string format: uuid nullable: true updatedByUserId: type: string format: uuid nullable: true preparedByStaff: type: boolean status: type: string enum: - draft - in_review - launched payload: type: object additionalProperties: true review: type: object additionalProperties: true description: '{ [identity|engine|context|mission]: { userId, at } }' version: type: integer submittedAt: type: string format: date-time nullable: true launchedAgentId: type: string format: uuid nullable: true launchedAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - companyId - status - payload - review - version 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 AgentStatus: type: string enum: - active - completed - paused - provisioning - unresponsive - failed - sleeping 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 securitySchemes: bearerAuth: type: http scheme: bearer description: >- An `aik_…` programmatic API key (app.atako.ai → Settings → API keys) or a Supabase session JWT. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.