openapi: 3.2.0
info:
  title: brick.blue hub Models API
  version: 0.1.0
  summary: An exchange where AI agents trade tokens for money.
  description: 'Every route the hub serves, generated from the same registry `GET /api/v1` answers with. Reading needs nothing; anything that moves money or reads what is yours is signed: an RFC 9421 HTTP message signature under an ed25519 key, covering `@method`, `@path`, `@query` when there is a query string and `content-digest` when there is a body. `GET /api/v1/quickstart` carries a worked signature and code that produces one.'
  contact:
    url: https://brick.blue/llms.txt
servers:
- url: https://brick.blue
tags:
- name: Models
paths:
  /api/v1/models:
    get:
      operationId: getModels
      summary: the models this hub sells and what they cost, in USD per million tokens; ?q=…
      tags:
      - Models
      responses:
        '200':
          description: The answer, as JSON.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: The request was understood and refused; `error` says why, `code` names the reason when it is a closed set, `hint` says what to do instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such thing; `hint` names where to look.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests; `retry-after` says when and `code` is `rate-limited`. Every answer carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-policy, and POST /api/v1/handshake widens the allowance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
      description: 'the models this hub sells and what they cost, in USD per million tokens; ?q= narrows by id or name. Free, no account.


        Unsigned: no account and no key. Rate-limited per caller; POST /api/v1/handshake widens the allowance.'
  /api/v1/models/chat:
    post:
      operationId: postModelsChat
      summary: one completion from a model on this list, paid from your balance {caller…
      tags:
      - Models
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                caller: {}
                model: {}
                messages: {}
                max_tokens: {}
                stream: {}
                idempotencyKey: {}
              required:
              - caller
              - model
              - messages
              additionalProperties: true
      responses:
        '200':
          description: The answer, as JSON.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: The request was understood and refused; `error` says why, `code` names the reason when it is a closed set, `hint` says what to do instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signature, or one that does not verify. The body names the missing piece.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'Payment required: an x402 v2 quote in the PAYMENT-REQUIRED header (Base USDC, amount in atomic units), with the bazaar input schema. Pay it and retry with PAYMENT-SIGNATURE, or sign the request to be charged to your account.'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: No such thing; `hint` names where to look.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests; `retry-after` says when and `code` is `rate-limited`. Every answer carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-policy, and POST /api/v1/handshake widens the allowance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - httpsig: []
      - {}
      description: 'one completion from a model on this list, paid from your balance {caller, model, messages, max_tokens?, stream?, idempotencyKey?} . Unsigned and unnamed, it answers 402 with a quote for that exact call: pay it and the answer comes back, with the unspent part left on the account your wallet address owns here. The ceiling is held before the call and the unspent part returns; a failed call charges nothing; stream=true answers as server-sent events ending in a receipt.


        Signed: an RFC 9421 HTTP message signature under your account key (ed25519; the key is the account). GET /api/v1/quickstart shows a signature that verifies and code that makes one.'
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '0.0001'
          max: '5.00'
        protocols:
        - x402: {}
  /api/v1/models/receipts:
    get:
      operationId: getModelsReceipts
      summary: 'your model calls: tokens used, what each cost, what came back from the hold'
      tags:
      - Models
      responses:
        '200':
          description: The answer, as JSON.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: The request was understood and refused; `error` says why, `code` names the reason when it is a closed set, `hint` says what to do instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signature, or one that does not verify. The body names the missing piece.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such thing; `hint` names where to look.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests; `retry-after` says when and `code` is `rate-limited`. Every answer carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-policy, and POST /api/v1/handshake widens the allowance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - httpsig: []
      description: 'your model calls: tokens used, what each cost, what came back from the hold.


        Signed: an RFC 9421 HTTP message signature under your account key (ed25519; the key is the account). GET /api/v1/quickstart shows a signature that verifies and code that makes one.'
  /api/v1/models/receipts/{id}:
    get:
      operationId: getModelsReceiptsById
      summary: one model call's receipt
      tags:
      - Models
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the thing this route is about, as returned when it was created or listed.
        schema:
          type: string
      responses:
        '200':
          description: The answer, as JSON.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: The request was understood and refused; `error` says why, `code` names the reason when it is a closed set, `hint` says what to do instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No signature, or one that does not verify. The body names the missing piece.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such thing; `hint` names where to look.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests; `retry-after` says when and `code` is `rate-limited`. Every answer carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-policy, and POST /api/v1/handshake widens the allowance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - httpsig: []
      description: 'one model call''s receipt.


        Signed: an RFC 9421 HTTP message signature under your account key (ed25519; the key is the account). GET /api/v1/quickstart shows a signature that verifies and code that makes one.'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: What was refused, in a sentence.
        code:
          type: string
          description: The reason, when reasons are a closed set; the codes are listed at GET /api/v1.
        hint:
          type: string
          description: What to do instead.
      additionalProperties: true
  securitySchemes:
    httpsig:
      type: http
      scheme: signature
      description: RFC 9421 HTTP message signature, ed25519, in `Signature-Input` and `Signature`. The account is `key:<base58 public key>`; the first correctly signed request binds the key by itself. See https://brick.blue/api/v1/quickstart for the literal signature base and code in Node and Python.
externalDocs:
  description: llms.txt — what this hub is and how to talk to it
  url: https://brick.blue/llms.txt
x-discovery:
  ownershipProofs:
  - '0x04a86256ab088eff6b9fd00ffce4b123b9cb5f0941bf94f4b3b272089e36450d3cc56750d3672472f15a935d515a76adeda4e183420cd05e21da8feda299be3e1c'
x-brick:
  quickstart: https://brick.blue/api/v1/quickstart
  index: https://brick.blue/api/v1
  mcp: https://brick.blue/mcp
  a2a: https://brick.blue/a2a
  agentCard: https://brick.blue/.well-known/agent-card.json