mahastrategies-com Buyer Brief API

openapi: 3.2.0
info:
  title: Maha Strategies MPS Buyer Brief API
  version: '0.1'
  description: 'The Maha Provenance Standard (MPS) API runs claim-level provenance audits over prose. Every factual claim in a passage is excerpted, tagged (VERIFIED, SOURCED, BOUNDARY, ILLUSTRATIVE, UNVERIFIED), and returned with a rationale and a recommended action — so agents and editors can verify before they publish.


    ## Local bridge (CLI)


    Install the open-source local bridge and point Claude Code, Cursor, or any MCP client at it:


    ```sh

    npm install -g @mahastrategies/maha-mcp-bridge

    maha login # verify and store your credential

    maha serve # start the stdio MCP server

    ```


    Raw rows and credentials stay local; only locally-redacted context reaches the agent''s cloud model.


    ## Authentication


    Commercial endpoints use bearer credentials:


    ```

    Authorization: Bearer mhaic_your_credential_here

    ```


    Credentials are shown **exactly once** at purchase. Store them in a secret manager; never commit them, log them, or place them in URLs. Each credential is scoped to the MPS audit capability only — it cannot touch any other service. Lost credentials cannot be recovered, only replaced.


    The free preflight endpoint (`POST /api/audit`) needs no credential and is limited per visitor per day.


    ## The credit system


    Paid audits are prepaid. Each successful audit consumes one `mps_audit_invocation` credit; failed audits are refunded automatically in the same ledger.


    When a credential runs out of credits, the API responds with **`402 Payment Required`**:


    ```json

    {

    "error": { "code": "payment_required", "message": "This prepaid credential has no audit credits remaining." },

    "purchase": { "href": "/mps/audit-access", "checkoutEndpoint": "/api/mps-credits/checkout", "unit": "mps_audit_invocation" }

    }

    ```


    Treat `402` as a routine signal, not an error: follow `purchase.href` to buy another pack, or call the checkout endpoint programmatically. Balances live in an append-only double-entry ledger — every grant, consumption, refund, and manual correction is a permanent, hash-chained row.


    ## Idempotency and webhook resilience


    **Requests**: every audit takes a `clientRequestId` you choose (8–120 characters). Retrying with the same id and the same text returns the original result with `idempotentReplay: true` — never a duplicate charge. The same id with *different* text returns `409 Conflict`. Safe retry loop: keep the same id until you get a terminal status.


    **Payments**: Stripe webhooks are processed exactly once. Each event id is claimed atomically in the same database transaction that moves credits, so a redelivered webhook can never double-credit a balance — duplicates get `200 OK` with `"duplicate": true` and change nothing. A crash between claim and grant rolls both back together. You never need to reconcile double-grants; the ledger cannot express them.'
  contact:
    name: Maha Strategies
    url: https://www.mahastrategies.com/contact
servers:
- url: https://www.mahastrategies.com
tags:
- name: Buyer-Brief
  description: Prepared archive purchase, recovery and seller support. Check the live activation gate before paying.
paths:
  /api/v1/cabezon/buyer-brief:
    get:
      tags:
      - Buyer-Brief
      operationId: getBuyerBriefContract
      security: []
      summary: Free pinned artifact metadata, terms and current purchase gate
      responses:
        '200':
          description: Metadata only, not archive contents. purchaseEnabled must be true before purchase.
        '503':
          description: Private artifact unavailable; do not pay.
    post:
      tags:
      - Buyer-Brief
      operationId: purchaseBuyerBrief
      security: []
      summary: Purchase the prepared Buyer-Brief archive for 20 USDC
      description: Only payable after activation. x402-only, Base native USDC. Save the random recovery secret before signing. No extra API calls are included.
      parameters:
      - name: x-maha-idempotency-key
        in: header
        required: true
        schema:
          type: string
        description: '{"preimage":"clientRequestId","algorithm":"identity","format":"8-120 ASCII letters/digits/underscore/hyphen"}'
      - name: x-maha-input-hash
        in: header
        required: true
        schema:
          type: string
        description: '{"preimage":"UTF-8 JSON.stringify({clientRequestId,version,bundleHash,termsHash,recoverySecret}) in exactly this key order, no whitespace","algorithm":"SHA-256","format":"sha256:<lowercase hex>"}'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - clientRequestId
              - version
              - bundleHash
              - termsHash
              - recoverySecret
              properties:
                clientRequestId:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{8,120}$
                version:
                  const: 2.0.0
                bundleHash:
                  type: string
                  pattern: ^sha256:[a-f0-9]{64}$
                  description: Use the exact GET contract value, not the placeholder.
                termsHash:
                  const: sha256:be78c3b480493b4d4347e9417644cbd8c4f84fdafd844fa4123b6e2fc8a0d122
                recoverySecret:
                  type: string
                  description: Generate a fresh cryptographically random 32-byte value locally. Never use a published example or put it in a URL.
      responses:
        '200':
          description: Pinned archive bytes; verify digest and review contents. Not buyer acceptance.
        '400':
          description: Invalid request; no new payment.
        '402':
          description: Unsigned x402 quote; no purchase.
          headers:
            PAYMENT-REQUIRED:
              schema:
                type: string
        '409':
          description: Changed bundle or mismatched order binding; reapprove before signing.
        '503':
          description: Unavailable or outcome unknown; reconcile, do not pay again.
  /api/v1/cabezon/buyer-brief/retrieve:
    post:
      tags:
      - Buyer-Brief
      operationId: recoverBuyerBrief
      security: []
      summary: Recover a settled order without repayment
      description: POST saved payer and exact order, including the private recovery secret. Never send a payment header or put the secret in the URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - payer
              - order
              properties:
                payer:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                order:
                  type: object
                  additionalProperties: false
                  required:
                  - clientRequestId
                  - version
                  - bundleHash
                  - termsHash
                  - recoverySecret
                  properties:
                    clientRequestId:
                      type: string
                      pattern: ^[A-Za-z0-9_-]{8,120}$
                    version:
                      const: 2.0.0
                    bundleHash:
                      type: string
                      pattern: ^sha256:[a-f0-9]{64}$
                      description: Use the exact GET contract value, not the placeholder.
                    termsHash:
                      const: sha256:be78c3b480493b4d4347e9417644cbd8c4f84fdafd844fa4123b6e2fc8a0d122
                    recoverySecret:
                      type: string
                      description: Generate a fresh cryptographically random 32-byte value locally. Never use a published example or put it in a URL.
      responses:
        '200':
          description: Pinned archive bytes; verify digest and review contents. Not buyer acceptance.
        '400':
          description: Invalid request; no new payment.
        '404':
          description: Recovery unavailable; contact seller, do not repay.
        '503':
          description: Unavailable or outcome unknown; reconcile, do not pay again.
  /api/v1/cabezon/buyer-brief/support:
    post:
      tags:
      - Buyer-Brief
      operationId: requestBuyerBriefSupport
      security: []
      summary: Queue an authenticated delivery, correction or refund request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - payer
              - order
              - kind
              properties:
                payer:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                order:
                  type: object
                  additionalProperties: false
                  required:
                  - clientRequestId
                  - version
                  - bundleHash
                  - termsHash
                  - recoverySecret
                  properties:
                    clientRequestId:
                      type: string
                      pattern: ^[A-Za-z0-9_-]{8,120}$
                    version:
                      const: 2.0.0
                    bundleHash:
                      type: string
                      pattern: ^sha256:[a-f0-9]{64}$
                      description: Use the exact GET contract value, not the placeholder.
                    termsHash:
                      const: sha256:be78c3b480493b4d4347e9417644cbd8c4f84fdafd844fa4123b6e2fc8a0d122
                    recoverySecret:
                      type: string
                      description: Generate a fresh cryptographically random 32-byte value locally. Never use a published example or put it in a URL.
                kind:
                  enum:
                  - delivery_problem
                  - correction_requested
                  - refund_requested
      responses:
        '202':
          description: Ticket queued; email delivery and refund are not confirmed.
        '400':
          description: Invalid request; no new payment.
        '503':
          description: Unavailable or outcome unknown; reconcile, do not pay again.
components:
  securitySchemes:
    credential:
      type: http
      scheme: bearer
      description: MPS client credential (`mhaic_…`), issued once at purchase.