Beancount.io Ledger API

openapi: 3.2.0
info:
  title: Beancount.io Ledger API
  description: Plain-Text Accounting. Powerful, Precise, Auditable. — Plain-text double-entry accounting with git versioning, BQL queries, CSV import, and MCP integration. Use scoped API keys or OAuth 2.1. See /mcp for Model Context Protocol and /graphql for the GraphQL endpoint. Free tier available; sandbox at https://beancount.io/demo.
  version: 1.0.0
  contact:
    name: Beancount.io
    url: https://beancount.io
    email: hello@beancount.io
  license:
    name: MIT
    url: https://opensource.org/license/mit
servers:
- url: https://beancount.io
  description: Production
security:
- ApiKeyAuth: []
- OAuth2:
  - read
  - write
tags:
- name: Ledger
  description: Ledger file and BQL operations
paths:
  /api-gateway/mcp:
    post:
      operationId: mcpCall
      summary: MCP tool invocation (Streamable HTTP)
      description: Model Context Protocol endpoint implementing Streamable HTTP transport. One tool per operation, including runBqlQuery (typed BQL), listLedgerFiles, readLedgerFiles, appendLedgerText, and createLedgerFiles/updateLedgerFiles/deleteLedgerFiles (atomic git commit with dry-run); the live list is https://beancount.io/.well-known/mcp.json. OAuth 2.1 required with scoped permissions. Returns JSON-RPC 2.0 with structured errors. See https://beancount.io/mcp for setup.
      tags:
      - Ledger
      security:
      - OAuth2:
        - read
        - write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - method
              properties:
                jsonrpc:
                  type: string
                  enum:
                  - '2.0'
                id:
                  type: string
                method:
                  type: string
                  enum:
                  - tools/list
                  - tools/call
                  - initialize
                  - ping
                params:
                  type: object
                  description: Tool-specific parameters - typed per tool
      responses:
        '200':
          description: MCP JSON-RPC response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /docs/{slug}:
    get:
      operationId: getDoc
      summary: Get documentation page
      description: 'Docs are available as HTML and via Accept: text/markdown or /docs/{slug}.md suffix. Vary: Accept ensures correct CDN caching.'
      tags:
      - Ledger
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: Doc slug, e.g. introduction-to-beancount
      - name: Accept
        in: header
        schema:
          type: string
        description: text/markdown for markdown variant
      responses:
        '200':
          description: Doc page
          headers:
            Vary:
              schema:
                type: string
          content:
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
components:
  schemas:
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code, e.g. BAD_REQUEST, UNAUTHORIZED, RATE_LIMITED
        message:
          type: string
          description: Human-readable message
        hint:
          type: string
          description: Resolution hint - what to do next
        details:
          type: object
          additionalProperties: true
          description: Optional structured details
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Scoped API key. Roles: read (query content/ledgers), write (ledger edits), admin (full). Request only needed scopes. Self-serve keys via dashboard; free tier and sandbox available at /demo. Rotate via API.'
    OAuth2:
      type: oauth2
      description: OAuth 2.1 with PKCE for MCP and GraphQL. Scopes enforce least privilege.
      flows:
        authorizationCode:
          authorizationUrl: https://beancount.io/oauth/authorize
          tokenUrl: https://beancount.io/oauth/token
          scopes:
            read: Read ledgers, queries, and content
            write: Edit ledgers and commit changes
            admin: Full administrative access
        clientCredentials:
          tokenUrl: https://beancount.io/oauth/token
          scopes:
            read: Read ledgers, queries, and content
            write: Edit ledgers and commit changes