Automo Openapi.json API

openapi: 3.2.0
info:
  title: Automo Build Openapi.json API
  version: 1.3.0
  description: 'The machine surface of Automo Build, the AI app builder. All capability calls go through the MCP endpoint (Model Context Protocol, Streamable HTTP): tools are discovered live via tools/list after OAuth sign-in. This document describes that endpoint, the OAuth 2.1 authorization server that protects it, and the discovery documents around them. Start at the server card or the protected-resource metadata; the site overview for agents is https://automo.build/llms.txt; agent registration is walked through at https://automo.build/auth.md.


    Rate limits: the unauthenticated endpoints answer with RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds), counted per client IP. MCP tool calls carry the same headers for the connection''s read, write or spawn budget. Past the limit the answer is 429 with Retry-After.


    Idempotency: POST /agent/identity accepts an Idempotency-Key header (16 to 255 printable characters, a UUID is ideal). A retry with the same key and body answers about the same registration instead of opening a second one; the same key with a different body is refused with 422.


    Versioning and deprecation: the MCP endpoint is versioned by the MCP-Protocol-Version header, whose values are MCP revision dates; every revision listed for it is served from the same URL. info.version follows semantic versioning: additions bump the minor version, breaking changes the major. Before a protocol revision or an operation is removed it is marked deprecated in this document and its responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers for at least 90 days.'
  contact:
    name: Automo Build
    url: https://automo.build/contact
    email: support@automo.ai
servers:
- url: https://mcp.automo.build
security:
- oauth2:
  - workspaces:read
  - projects:read
  - projects:write
  - prompts:write
  - sessions:read
  - sessions:write
  - reviews:read
  - reviews:write
  - playbooks:read
  - playbooks:run
  - playbooks:write
  - deployments:read
  - deployments:write
  - chat:read
  - billing:write
tags:
- name: Openapi.json
paths:
  /openapi.json:
    get:
      operationId: getOpenApi
      summary: This document
      responses:
        '200':
          description: OpenAPI 3.1
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
      - Openapi.json
components:
  headers:
    RateLimitReset:
      description: Seconds until the window frees a request
      schema:
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying
      schema:
        type: integer
    RateLimitPolicy:
      description: The limit and its window, as "<limit>;w=<seconds>"
      schema:
        type: string
    RateLimitLimit:
      description: Requests allowed in the current window
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current window
      schema:
        type: integer
  schemas:
    OAuthError:
      type: object
      description: RFC 6749 error body
      properties:
        error:
          type: string
        error_description:
          type: string
      required:
      - error
  responses:
    TooManyRequests:
      description: Rate limited; wait Retry-After seconds
      headers:
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Automo Build OAuth 2.1: authorization code with PKCE (S256). Clients register by Client ID Metadata Document (the client_id is an HTTPS URL); there is no dynamic client registration. Tokens are JWTs bound to the resource URL, one hour, with rotating refresh tokens.'
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.automo.build/oauth/authorize
          tokenUrl: https://mcp.automo.build/oauth/token
          refreshUrl: https://mcp.automo.build/oauth/token
          scopes:
            workspaces:read: List workspace memberships, whoami, switch the current workspace
            projects:read: List and search projects, project status, env var names, screenshots, deployment history
            projects:write: Create projects, wake sandboxes, share and clone links
            prompts:write: Prompt a project's main agent
            sessions:read: Read any agent session the user can read in the app
            sessions:write: Open, continue and stop agent sessions (CTO, Doctor, Security, QA, Architect, builder spawns)
            reviews:read: 'The sign-off state of builder work: cards, verdicts, fixes, whose move it is'
            reviews:write: Promote, ask a reviewer, hand fixes to the builder, approve or cancel a review
            playbooks:read: List playbooks and read their runs
            playbooks:run: Run a playbook
            playbooks:write: Create and edit playbooks
            deployments:read: Pending publish, deployment status and history
            deployments:write: Propose and approve deployments, publish
            chat:read: Read project chat history
            billing:write: Put a workspace on the Free plan