audit.domains Machine API

openapi: 3.2.0
info:
  title: audit.domains resolve Machine API
  version: 1.4.0
  description: 'The keyless lane for software that cannot hold an API key. One endpoint, /api/machine/resolve. GET returns the live terms, including which payment lanes are open right now (payments.card.status and payments.x402.status). The card lane is a $5 Square checkout: no account, no sign-in, and a person opens the checkout link to pay. The prepaid balance lane is for a funded agent with no person in the loop: a signed-in human operator loads a balance and grants the agent an expiring limit at https://audit.domains/machine-account, then the agent POSTs action purchase (version purchase-1, operationId, grantId, domain, intent, maxSpendUsd) and recovers with purchase_status; new purchases are available only when GET reports settlement.balance and recoverablePurchases.purchaseOpen true, and only for settlement.sellable products. recoverablePurchases.enabled describes receipt recovery, which can remain available when new sales close. When no payment lane can deliver the requested operator-account product, its quote returns 503 product_unavailable with availableProducts and no purchase action. Independent card or x402 offers remain available when their own lane can deliver. The x402 lane is closed unless GET reports payments.x402.status open. The keyed API (ad_live_ keys, https://audit.domains/api/openapi.json) is the other paid route and is not needed here. Names with a published figure are free at https://audit.domains/domain/{name}/index.json and are refused on the card lane with 409 free_in_catalog. An authenticated agent can inspect only its own existing grants using action agent_status, version agent-status-1. This read-only, private snapshot shows exact scopes, expiry, residual credit capacity and remaining attempts without creating authority. Download https://audit.domains/agent-planner.mjs with agent-purchase-plan.mjs and agent-buyer.mjs for dependency-free Node 22 preflight; planning never reserves credits or executes a purchase.'
servers:
- url: https://audit.domains
tags:
- name: machine
paths:
  /api/machine/resolve:
    get:
      summary: 'Live terms: products, open payment lanes and how to pay'
      operationId: machineTerms
      responses:
        '200':
          description: Terms document. Read payments.card.status, payments.x402.status, and settlement.balance. Funded new sales also require recoverablePurchases.purchaseOpen and a product in settlement.sellable; recoverablePurchases.enabled alone only confirms that receipt recovery is available.
          content:
            application/json:
              schema:
                type: object
      tags:
      - machine
    post:
      summary: Buy with an existing funded grant, recover a purchase, use card checkout, or…
      description: 'For unattended purchases, use Authorization: Bearer ad_agent_ and action purchase with version purchase-1, a persisted operationId, an existing operator-issued grantId, domain, intent and explicit maxSpendUsd. The route enforces grant scope, expiry, balance and spending limits. Persist the original arguments before sending. Recover with purchase_status; a pending delivery resumes only by retrying purchase with the SAME operationId and original arguments after retryAfterSeconds. Never increase the ceiling or choose a new identifier for recovery. For card_checkout, a person pays at the returned Square checkoutUrl; keep orderId and secret orderToken and poll card_status. Card credentials are shown once. card_checkout is idempotent on operationId: repeating it with the same domain and intent returns the same orderId with no checkoutUrl (status checkout_exists), never a second payable order; a repeat that changes the domain or intent is operation_id_conflict (409), and the orderToken is shown only at the first checkout for an operationId. A paid card order that cannot be delivered is refunded. For agent card purchases, use action card_agent_pay with version card-agent-1, a persisted operationId, an existing grantId, an enrolled cardRef, domain, intent and explicit maxSpendUsd. The cardholder enrolls the card once, in person, at /api/machine/card-enroll; after enrollment no person and no checkout page is involved. Repeat the identical card_agent_pay request with the same operationId to recover any uncertain outcome; it never charges twice. Recover state at any time with card_agent_status and the operationId alone. Without an action, a free intent answers 200. A supported paid intent answers 402 with the available offer; when no lane can deliver the requested operator-account product, its quote answers 503 product_unavailable, availableProducts and no purchase action. Existing purchase and purchase_status requests can recover their original receipts even when new sales close. Live GET terms are authoritative about available payment lanes and products. For read-only authority discovery, send action agent_status with version agent-status-1 and the agent bearer, with no caller identity fields. A snapshot is advisory and non-reserving; capacity can change before purchase. Truncated snapshots must not be used for automatic grant selection. The planner intersects an explicit buyer cap, authoritative free quote and exact grant scope, choosing the least authority deterministically. It never replaces an existing operation journal.'
      operationId: machineResolve
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/AgentStatus'
              - $ref: '#/components/schemas/AgentPurchase'
              - $ref: '#/components/schemas/AgentPurchaseStatus'
              - $ref: '#/components/schemas/CardCheckout'
              - $ref: '#/components/schemas/CardStatus'
              - $ref: '#/components/schemas/CardAgentPay'
              - $ref: '#/components/schemas/CardAgentStatus'
              - $ref: '#/components/schemas/Resolve'
            examples:
              quote:
                summary: 'Step 0 of the canonical recipe fresh-appraisal-purchase-1: quote only. No action field; a paid intent answers 402 with the offer and never charges.'
                value:
                  domain: example.com
                  intent: appraise
                  maxSpendUsd: 0.03
              checkout:
                value:
                  action: card_checkout
                  domain: example.com
                  intent: appraise
                  operationId: my-order-0001
              status:
                value:
                  action: card_status
                  orderId: <orderId from card_checkout>
                  orderToken: <64 hex characters from card_checkout>
              cardAgentPay:
                value:
                  action: card_agent_pay
                  version: card-agent-1
                  operationId: my-card-purchase-0001
                  grantId: 33333333-3333-4333-8333-333333333333
                  cardRef: acr_0123456789abcdef0123456789abcdef
                  domain: example.com
                  intent: appraise
                  maxSpendUsd: 5
              cardAgentStatus:
                value:
                  action: card_agent_status
                  version: card-agent-1
                  operationId: my-card-purchase-0001
              purchase:
                summary: 'Step 1 of the canonical recipe fresh-appraisal-purchase-1: the only step that moves money. Step 2 is purchaseStatus with the same operationId.'
                value:
                  action: purchase
                  version: purchase-1
                  operationId: my-purchase-0001
                  grantId: 33333333-3333-4333-8333-333333333333
                  domain: example.com
                  intent: appraise
                  maxSpendUsd: 0.03
              purchaseStatus:
                value:
                  action: purchase_status
                  version: purchase-1
                  operationId: my-purchase-0001
              agentAuthority:
                value:
                  action: agent_status
                  version: agent-status-1
      responses:
        '200':
          description: A fulfilled funded-purchase receipt, a card checkout link, a delivered card appraisal, or a free result. Or a private advisory agent-status-1 snapshot of the authenticated agent's own grants.
          content:
            application/json:
              schema:
                type: object
        '202':
          description: Pending funded purchase, awaiting card payment, or delivery in progress. Respect retryAfterSeconds or Retry-After. Status reads do not resume a funded purchase; retry its original purchase request with the same operationId.
        '400':
          description: Invalid request, such as operation_id_invalid, domain_and_intent_required or order_token_required.
        '402':
          description: Paid offer, insufficient prepaid balance, or insufficient scoped grant budget. No automatic funding or ceiling increase.
        '404':
          description: Unknown purchase operation, unknown card order or wrong card token, or endpoint disabled.
        '409':
          description: A refunded funded-purchase receipt restores service credits to the account. Operation conflict refuses changes to an existing funded request. Card free_in_catalog returns the published figureUrl.
        '429':
          description: rate_limited. Retry later.
        '503':
          description: Purchase authority, payment lane, product or engine unavailable. An uncertain purchase outcome must be recovered using the original operationId; do not assume no credits were charged.
        '401':
          description: Funded purchase requires a valid expiring ad_agent_ bearer.
        '403':
          description: Authenticated agent lacks the required scoped grant authority, or its grant is expired or revoked.
      tags:
      - machine
      security:
      - {}
      - AgentBearer: []
components:
  schemas:
    Resolve:
      type: object
      required:
      - domain
      - intent
      properties:
        domain:
          type: string
        intent:
          type: string
          enum:
          - screen
          - appraise
          - evidence
          - acquire
          - monitor
        maxSpendUsd:
          type: number
          minimum: 0
      additionalProperties: false
    CardCheckout:
      type: object
      required:
      - action
      - domain
      - operationId
      properties:
        action:
          const: card_checkout
        domain:
          type: string
          examples:
          - example.com
        intent:
          type: string
          default: appraise
        operationId:
          type: string
          pattern: ^[A-Za-z0-9._:-]{8,128}$
          description: A label you choose for this order.
    CardStatus:
      type: object
      required:
      - action
      - orderId
      - orderToken
      properties:
        action:
          const: card_status
        orderId:
          type: string
          pattern: ^[A-Za-z0-9_-]{8,64}$
        orderToken:
          type: string
          pattern: ^[0-9a-f]{64}$
    AgentPurchase:
      type: object
      additionalProperties: false
      required:
      - action
      - version
      - operationId
      - grantId
      - domain
      - intent
      - maxSpendUsd
      properties:
        action:
          const: purchase
        version:
          const: purchase-1
        operationId:
          type: string
          pattern: ^[A-Za-z0-9._:-]{8,128}$
          description: Persist before purchase. Reuse this identifier and the original request for every recovery attempt.
        grantId:
          type: string
          format: uuid
          description: An existing operator-issued grant; this endpoint cannot create or widen it.
        domain:
          type: string
        intent:
          type: string
          enum:
          - screen
          - appraise
          - evidence
          - acquire
          - monitor
          description: Only products reporting live availability in GET terms can be delivered.
        maxSpendUsd:
          type: number
          minimum: 0
          description: Explicit USD-equivalent service-credit ceiling. A zero ceiling cannot buy a paid service.
    CardAgentPay:
      type: object
      required:
      - action
      - version
      - operationId
      - grantId
      - cardRef
      - domain
      - maxSpendUsd
      properties:
        action:
          const: card_agent_pay
        version:
          const: card-agent-1
        operationId:
          type: string
          pattern: ^[A-Za-z0-9._:-]{8,128}$
          description: Your idempotency key for this charge. Persist it before sending; repeat the identical request to recover any uncertain outcome.
        grantId:
          type: string
          format: uuid
          description: An operator-issued grant naming product current_appraisal.
        cardRef:
          type: string
          pattern: ^acr_[0-9a-f]{32}$
          description: The enrolled card handle from enrollment. Never a card number.
        domain:
          type: string
          examples:
          - example.com
        intent:
          type: string
          const: appraise
        maxSpendUsd:
          type: number
          exclusiveMinimum: 0
          description: Your hard ceiling for this charge. Below the price, the answer is ceiling_below_price and nothing is charged.
    CardAgentStatus:
      type: object
      required:
      - action
      - version
      - operationId
      properties:
        action:
          const: card_agent_status
        version:
          const: card-agent-1
        operationId:
          type: string
          pattern: ^[A-Za-z0-9._:-]{8,128}$
    AgentPurchaseStatus:
      type: object
      additionalProperties: false
      required:
      - action
      - version
      - operationId
      properties:
        action:
          const: purchase_status
        version:
          const: purchase-1
        operationId:
          type: string
          pattern: ^[A-Za-z0-9._:-]{8,128}$
          description: Persist before purchase. Reuse this identifier and the original request for every recovery attempt.
    AgentStatus:
      type: object
      additionalProperties: false
      required:
      - action
      - version
      properties:
        action:
          const: agent_status
        version:
          const: agent-status-1
      description: 'Read-only authenticated own-grant snapshot. Uses AgentBearer; identity comes exclusively from the verified token. No operation, funding, mutation, account initialization or engine call. Responses use private, no-store and Vary: Authorization.'
  securitySchemes:
    AgentBearer:
      type: http
      scheme: bearer
      description: An existing operator-issued expiring ad_agent_ token. Required for purchase, purchase_status, card_agent_pay and card_agent_status; never place the token in JSON arguments.