> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiybiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an agent

> Requires an active subscription and `canCreateAgents` permission. Guards, checked in order: AGENT_CREATION_NOT_ALLOWED (403), AGENT_LIMIT_REACHED (403), NO_ACTIVE_SUBSCRIPTION (402), MODEL_NOT_FOUND/HARNESS_NOT_FOUND (400), CLIENT_NOT_FOUND (404).



## OpenAPI

````yaml /api-reference/openapi.json post /agents
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, with all of that user's permissions —
    there is no separate key scope in this release.


    ## Other Atako HTTP surfaces (not covered by this spec)


    - **Atako MCP server** — `POST /mcp` (auth: same Bearer token as above)
    exposes a read-only Model Context Protocol tool catalogue for AI clients
    (Claude Code, Claude Desktop, Cursor, ChatGPT). See
    [docs.atako.ai/developers/mcp/overview](https://docs.atako.ai/developers/mcp/overview).

    - **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: Public
  - name: Marketing Content
paths:
  /agents:
    post:
      tags:
        - Agents
      summary: Create an agent
      description: >-
        Requires an active subscription and `canCreateAgents` permission.
        Guards, checked in order: AGENT_CREATION_NOT_ALLOWED (403),
        AGENT_LIMIT_REACHED (403), NO_ACTIVE_SUBSCRIPTION (402),
        MODEL_NOT_FOUND/HARNESS_NOT_FOUND (400), CLIENT_NOT_FOUND (404).
      operationId: createAgent
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentBody'
      responses:
        '201':
          description: The created agent (raw row).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRecord'
        '400':
          description: Missing/invalid field, unknown model/harness, or invalid engine.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, malformed, or invalid bearer token / API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: NO_ACTIVE_SUBSCRIPTION
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            AGENT_CREATION_NOT_ALLOWED / NOT_TEAM_MEMBER / AGENT_LIMIT_REACHED /
            BYOK_DISABLED / BYOK_NOT_ALLOWED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: CLIENT_NOT_FOUND / PROVIDER_KEY_NOT_FOUND
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateAgentBody:
      type: object
      required:
        - name
        - image
      properties:
        name:
          type: string
          minLength: 1
        image:
          type: string
          description: PNG filename under apps/web/public/aiygents/.
        systemPrompt:
          type: string
          nullable: true
          description: Free-text agent instructions, trimmed.
        clientContext:
          type: string
          description: Free-text per-agent business context, trimmed.
        modelId:
          type: string
          format: uuid
          description: From GET /models. Omitted → admin-declared default model.
        harnessId:
          type: string
          format: uuid
          description: From GET /harnesses.
        teamId:
          type: string
          format: uuid
          nullable: true
          description: Assigns the agent to a shared team instead of keeping it personal.
        modelConfig:
          type: object
          description: >-
            Per-task-type model overrides, forwarded to the orchestrator
            webhook.
          properties:
            vision:
              type: string
              nullable: true
            low_effort:
              type: string
              nullable: true
            medium_effort:
              type: string
              nullable: true
            high_effort:
              type: string
              nullable: true
        engine:
          type: string
          enum:
            - openclaw
            - hermes
          description: Defaults to openclaw.
        llmKeyId:
          type: string
          format: uuid
          description: >-
            BYOK: id of a company LLM provider key (see docs — BYOK key
            management is not part of this customer API cut).
    AgentRecord:
      type: object
      description: >-
        The raw `agents` table row, returned verbatim by POST /agents (201) and
        POST /agents/{id}/end (200, under `.session`). Every column, including
        several operational/internal fields not otherwise exposed.
      properties:
        id:
          type: string
          format: uuid
        clientId:
          type: string
          format: uuid
        teamId:
          type: string
          format: uuid
          nullable: true
        companyId:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        image:
          type: string
        systemPrompt:
          type: string
          nullable: true
        modelId:
          type: string
          format: uuid
          nullable: true
        directModelId:
          type: string
          nullable: true
        modelConfig:
          type: object
          nullable: true
          description: Per-task-type model overrides.
          properties:
            vision:
              type: string
              nullable: true
            low_effort:
              type: string
              nullable: true
            medium_effort:
              type: string
              nullable: true
            high_effort:
              type: string
              nullable: true
        llmKeyId:
          type: string
          format: uuid
          nullable: true
          description: >-
            Set for a BYOK agent (company LLM provider key); null for the
            platform key.
        harnessId:
          type: string
          format: uuid
          nullable: true
        engine:
          type: string
          enum:
            - openclaw
            - hermes
        status:
          $ref: '#/components/schemas/AgentStatus'
        agentAuthTokenHash:
          type: string
          nullable: true
        agentAuthIssuedAt:
          type: string
          format: date-time
          nullable: true
        agentAuthLastUsedAt:
          type: string
          format: date-time
          nullable: true
        startDate:
          type: string
          format: date-time
        activatedAt:
          type: string
          format: date-time
          nullable: true
        endDate:
          type: string
          format: date-time
          nullable: true
        lastHeartbeatAt:
          type: string
          format: date-time
          nullable: true
        lastReadAt:
          type: string
          format: date-time
          nullable: true
        engineVersion:
          type: string
          nullable: true
        engineImage:
          type: string
          nullable: true
        engineRequestedVersion:
          type: string
          nullable: true
        upgradingAt:
          type: string
          format: date-time
          nullable: true
        upgradeRequestedAt:
          type: string
          format: date-time
          nullable: true
        upgradeStatus:
          type: string
          enum:
            - requested
            - running
            - succeeded
            - failed
          nullable: true
        upgradeError:
          type: string
          nullable: true
        provisioningError:
          type: string
          nullable: true
        pausedAt:
          type: string
          format: date-time
          nullable: true
        pausedReason:
          type: string
          nullable: true
        clientContext:
          type: string
          nullable: true
          description: Per-agent "contexte business" free text.
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - clientId
        - name
        - image
        - engine
        - status
        - startDate
        - createdAt
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An `aik_…` programmatic API key (app.atako.ai → Settings → API keys) or
        a Supabase session JWT.

````