openapi: 3.0.3
info:
  title: Aider CLI Chat Modes API
  version: 0.86.1
  description: Documentation surface for the Aider command-line interface. Aider has no hosted REST API and does not bind to a network port — it runs entirely in a developer's terminal against the local Git working tree. This OpenAPI document models the Aider command surface as if it were a REST API so it can be consumed by API-centric tooling (catalogs, registries, governance rule engines, capability runtimes). Each slash command (`/add`, `/diff`, `/commit`, etc.) is modeled as a path; each launch-flag family is modeled as a configuration path. Servers and security blocks are placeholders — aider's actual security model is "use the user's local shell credentials and the LLM provider API key in the environment."
  contact:
    name: Aider Maintainers
    url: https://github.com/Aider-AI/aider/issues
  license:
    name: Apache 2.0
    url: https://github.com/Aider-AI/aider/blob/main/LICENSE.txt
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
  x-source-urls:
  - https://aider.chat/docs/usage/commands.html
  - https://aider.chat/docs/usage/modes.html
  - https://aider.chat/docs/config/options.html
  - https://aider.chat/docs/llms.html
servers:
- url: cli://aider
  description: Local CLI invocation (not a network endpoint). Modeled as URI scheme `cli://aider` for catalog tooling.
- url: file:///usr/local/bin/aider
  description: Typical install path for the `aider` entrypoint.
security:
- LLMProviderKey: []
tags:
- name: Modes
  description: Aider Chat Modes (Code, Architect, Ask, Help, Context).
paths:
  /commands/architect:
    post:
      operationId: architectMode
      summary: Aider Enter Architect Mode
      description: Enter architect/editor mode using 2 different models — a reasoning model proposes, an editor model executes file edits. Maps to `/architect`.
      tags:
      - Modes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditRequest'
      responses:
        '200':
          description: Architect plan executed by editor model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditResult'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /commands/ask:
    post:
      operationId: askQuestion
      summary: Aider Ask Question About Code
      description: Ask questions about the code base without editing any files. Maps to the `/ask` in-chat command.
      tags:
      - Modes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      responses:
        '200':
          description: Answer returned without code changes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /commands/chat-mode:
    post:
      operationId: switchChatMode
      summary: Aider Switch Chat Mode
      description: Switch to a new chat mode (code, architect, ask, help, context). Maps to `/chat-mode`.
      tags:
      - Modes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatModeRequest'
      responses:
        '200':
          description: Chat mode changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /commands/help:
    get:
      operationId: getHelp
      summary: Aider Ask Help Question
      description: Ask questions about aider. Maps to `/help` and the `help` chat mode.
      tags:
      - Modes
      parameters:
      - name: query
        in: query
        required: false
        description: The help question to ask.
        schema:
          type: string
        example: how do I switch models?
      responses:
        '200':
          description: Help response returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    CommandResult:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        message:
          type: string
          example: Files added to chat.
    EditResult:
      type: object
      properties:
        files_changed:
          type: array
          description: File paths modified by this edit.
          items:
            type: string
            example: src/main.py
          example:
          - src/main.py
        commit_sha:
          type: string
          description: Git commit SHA produced by auto-commit.
          example: a1b2c3d4e5f6
        commit_message:
          type: string
          description: Auto-generated conventional commit message.
          example: 'feat(cache): switch to LRU eviction policy'
        tokens_in:
          type: integer
          description: Prompt tokens sent to the LLM.
          example: 4231
        tokens_out:
          type: integer
          description: Completion tokens received from the LLM.
          example: 1284
    AskResponse:
      type: object
      properties:
        answer:
          type: string
          description: Markdown answer from the LLM. No files are modified.
          example: The retry policy in `src/http/retry.py` wraps the rate limiter from `src/http/limiter.py` ...
        files_referenced:
          type: array
          description: Files the LLM cited in its answer.
          items:
            type: string
            example: src/http/retry.py
          example:
          - src/http/retry.py
          - src/http/limiter.py
    ChatModeRequest:
      type: object
      required:
      - mode
      properties:
        mode:
          type: string
          description: Chat mode to switch to.
          enum:
          - code
          - architect
          - ask
          - help
          - context
          example: architect
    EditRequest:
      type: object
      required:
      - prompt
      properties:
        prompt:
          type: string
          description: Natural-language instruction to apply to the in-chat files.
          example: Refactor the cache layer to use an LRU eviction policy and add unit tests.
        edit_format:
          type: string
          description: Edit format the LLM should produce.
          enum:
          - diff
          - whole
          - udiff
          - editor-diff
          example: diff
        auto_commit:
          type: boolean
          description: Whether to auto-commit edits via Git. Defaults to the launch-time setting.
          default: true
          example: true
    AskRequest:
      type: object
      required:
      - prompt
      properties:
        prompt:
          type: string
          description: Question to ask about the codebase.
          example: How does the retry policy in the http client interact with the rate limiter?
  securitySchemes:
    LLMProviderKey:
      type: apiKey
      in: header
      name: X-Provider-API-Key
      description: Placeholder for documentation purposes. Aider does not authenticate with an "aider API"; it reads the relevant upstream provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) from the local environment and passes it to the chosen LLM provider directly.