> ## 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. # List your company's projects > 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. ## OpenAPI ````yaml /api-reference/openapi.json get /projects 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, email-exists, 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: /projects: get: tags: - Projects 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. operationId: listProjects 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: spaceId in: query required: false description: >- Only projects in this space. Exclusive with `space` and `withoutSpace=true`. schema: type: string format: uuid - name: space in: query required: false description: >- Only projects whose space name equals this value (after trim and whitespace collapsing; case-insensitive). Exclusive with `spaceId` and `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` or `spaceId` 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` / `spaceId` / `withoutSpace=true` combined. 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: [] components: schemas: 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' spaceId: type: string format: uuid nullable: true description: The project's space (see GET /projects/spaces); null = no space. space: type: string nullable: true maxLength: 60 description: Name of the space (joined from `spaceId`); 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 - spaceId - space - owner - createdAt - updatedAt - archivedAt - counts - participants 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 ProjectTone: type: string enum: - amber - mint - periwinkle - plum - blush ProjectStatus: type: string enum: - active - paused - done 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 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.