AgentsIndex Agent API

openapi: 3.2.0
info:
  title: AgentsIndex — machine Agent API
  version: 1.0.0
  description: 'AgentsIndex is the reference index of AI-native tools: an ongoing, edited catalog of AI agents, AI-first products, and the tools that power them. Free, keyless read endpoints over the tools corpus, plus verified-session submission intake. AgentsIndex reuse terms (https://agentsindex.ai/terms): Search engines, AI assistants answering a question and AI models in training may all read and reuse these listings. Say the facts came from AgentsIndex and link the listing you used.'
  license:
    name: AgentsIndex reuse terms
    url: https://agentsindex.ai/terms
servers:
- url: https://agentsindex.ai
tags:
- name: Agent
paths:
  /api/agent/catalogue:
    get:
      operationId: getAgentCatalogue
      summary: What a listing owner can buy here, with prices excl.
      description: 'Keyless. Listing is free and never sold. Offers now: boost 29.00 USD (once). Same answer as the MCP tool list_offers.'
      security: []
      responses:
        '200':
          description: The catalogue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCatalogue'
      tags:
      - Agent
  /api/agent/quotes:
    post:
      operationId: getAgentQuote
      summary: A signed price for one offer on one listing, for the account that owns it
      description: 'Send the owner''s session or agent key. The answer is a quote_id, the price in cents and when it expires (30 minutes). Nothing is reserved or charged; POST /api/agent/orders turns it into an order. Refusals: 401 sign_in_required, 403 not_owner (with the claim page), 404 no_listing, 400 not_offered, 409 not_accepted, not_live, already_live, already_bought, category_full, 429 rate_limited. Each carries a fix.'
      security:
      - sessionCookie: []
      - agentKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - offer
              - listing
              properties:
                offer:
                  type: string
                  enum:
                  - boost
                listing:
                  type: string
                  description: The listing id or slug.
      responses:
        '201':
          description: The quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentQuote'
        '401':
          description: sign_in_required
          content:
            application/json:
              schema:
                type: object
        '403':
          description: not_owner
          content:
            application/json:
              schema:
                type: object
        '409':
          description: The listing cannot have the offer now; the fix says why.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
  /api/agent/orders:
    post:
      operationId: createAgentOrder
      summary: An order from a quote, payable by card for 24 hours
      description: 'The account that owns the listing: its session, or an agent key with the order scope. The same Idempotency-Key returns the same order. Refusals carry a fix. Nothing is charged here.'
      security:
      - sessionCookie: []
      - agentKey: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - quote_id
              properties:
                quote_id:
                  type: string
      responses:
        '200':
          description: The order this Idempotency-Key already made.
          content:
            application/json:
              schema:
                type: object
        '201':
          description: The order, with payment.url.
          content:
            application/json:
              schema:
                type: object
        '409':
          description: open_order, price_changed or idempotency_mismatch.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
  /api/agent/orders/{id}:
    get:
      operationId: getAgentOrder
      summary: Where an order is
      security: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: No order has that id.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
  /api/agent/orders/{id}/payment:
    post:
      operationId: payAgentOrder
      summary: Pay an order by card over HTTP 402
      description: 'No credential: 402 with a card challenge in WWW-Authenticate (MPP, method stripe: a Stripe Shared Payment Token for this site). With Authorization: Payment and the credential: the payment, the delivery, and the receipt (Payment-Receipt header, receipt_url). The order id is the capability; no key needed. Optional JSON body {"buyer": {"vat_id", "country", "company", "address"}} on both requests: an EU VAT ID that VIES confirms gets an invoice. The price is excl. VAT: EU buyers without a valid EU VAT ID pay 21% VAT on top, and the 402 shows the total.'
      security: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '29.00'
        protocols:
        - mpp:
            method: stripe
            intent: charge
            currency: usd
        offers:
        - method: stripe
          intent: charge
          amount: '2900'
          currency: usd
          description: VIP listing by card, through a Stripe Shared Payment Token
      responses:
        '200':
          description: 'Paid and delivered: the order, the payment and its receipt.'
          content:
            application/json:
              schema:
                type: object
        '402':
          description: 'Payment required: the card challenge in WWW-Authenticate, and in the body what it buys and how to pay.'
          content:
            application/json:
              schema:
                type: object
        '409':
          description: already_paid, payment_in_progress, expired, or the listing can no longer have the offer (nothing charged).
          content:
            application/json:
              schema:
                type: object
        '503':
          description: 'payments_unavailable: nothing was charged.'
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
  /api/agent/orders/{id}/receipt:
    get:
      operationId: getAgentOrderReceipt
      summary: The receipt of a paid order, as a page
      security: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The receipt page.
          content:
            text/html:
              schema:
                type: string
        '404':
          description: No paid order has that id.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
components:
  schemas:
    AgentCatalogue:
      type: object
      properties:
        site:
          type: string
        currency:
          const: usd
        vat:
          type: string
        offers:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              price_cents:
                type: integer
              currency:
                const: usd
              term:
                type: string
              includes:
                type: array
                items:
                  type: string
              needs:
                type: array
                items:
                  type: string
              rails:
                type: array
                items:
                  type: string
                description: 'mpp:stripe: a card through a Stripe Shared Payment Token.'
        quote:
          type: object
        ordering:
          type: object
    AgentQuote:
      type: object
      properties:
        quote_id:
          type: string
        offer:
          type: string
        listing:
          type: object
          properties:
            id:
              type: string
            slug:
              type: string
        price_cents:
          type: integer
        currency:
          const: usd
        term:
          type: string
        expires_at:
          type: string
          format: date-time
  securitySchemes:
    agentKey:
      type: http
      scheme: bearer
      description: An agent key the account made at https://agentsindex.ai/dashboard/agents (it starts with mak_). It acts as that account on submit, the claim and domain-proof steps, quotes, orders and reading its own listings, each by the scope the key was given, with the same refusals as its session; it cannot sign in, change the account or pay.
    sessionCookie:
      type: apiKey
      in: cookie
      name: __Secure-better-auth.session_token
      description: Existing Better Auth session cookie issued through https://agentsindex.ai/login?next=%2Fsubmit. The account email must be verified for submission. This is a session cookie, not an API key to provision.