mahastrategies-com Checkout API

openapi: 3.2.0
info:
  title: Maha Strategies MPS Checkout 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: Checkout
  description: Self-service credit purchase.
paths:
  /api/v1/billing/subscription:
    post:
      tags:
      - Checkout
      operationId: createTenantSubscriptionCheckout
      summary: Create Builder or Scale subscription Checkout for the authenticated tenant
      security:
      - credential: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tier
              - clientRequestId
              properties:
                tier:
                  type: string
                  enum:
                  - builder
                  - scale
                clientRequestId:
                  type: string
                  minLength: 8
                  maxLength: 120
                  pattern: ^[A-Za-z0-9_-]+$
                  description: Stable idempotency key for retrying this Checkout attempt.
      responses:
        '200':
          description: Hosted Stripe subscription Checkout URL.
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                properties:
                  url:
                    type: string
                    format: uri
        '400':
          description: Invalid tier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Tenant already has a subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Subscription Checkout unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/billing/settings:
    get:
      tags:
      - Checkout
      operationId: getTenantBillingSettings
      summary: Get tenant subscription balances and auto-top-up state
      security:
      - credential: []
      responses:
        '200':
          description: Sanitized tenant billing state; Stripe identifiers are not returned.
        '401':
          description: Invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Billing settings unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    post:
      tags:
      - Checkout
      operationId: updateTenantAutoTopup
      summary: Explicitly enable or disable tenant automatic top-up
      security:
      - credential: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - autoTopupEnabled
              properties:
                autoTopupEnabled:
                  type: boolean
      responses:
        '200':
          description: Updated automatic top-up state.
        '400':
          description: Invalid setting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: An active subscription and saved payment method are required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Billing settings unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/mps-credits:
    get:
      tags:
      - Checkout
      operationId: getCreditBalance
      summary: Check the credit balance for a credential
      description: Returns the live ledger balance and recent checkouts for the authenticated credential. Poll this to decide when to buy another pack before hitting `402`.
      security:
      - credential: []
      responses:
        '200':
          description: Current balance and recent checkout history.
          content:
            application/json:
              schema:
                type: object
                required:
                - clientId
                - unit
                - balance
                - billingEnforcement
                - checkouts
                properties:
                  clientId:
                    type: string
                    pattern: ^client_[a-f0-9]{32}$
                  unit:
                    type: string
                    const: mps_audit_invocation
                  balance:
                    type: number
                    description: Sum of all ledger entries for this client.
                  billingEnforcement:
                    type: string
                    enum:
                    - prepaid
                    - internal_meter
                  checkouts:
                    type: array
                    maxItems: 20
                    items:
                      type: object
                      properties:
                        public_id:
                          type: string
                          pattern: ^credit_checkout_[a-f0-9]{32}$
                        credit_quantity:
                          type: integer
                        status:
                          type: string
                          enum:
                          - awaiting_payment
                          - paid
                          - failed
                        created_at:
                          type: string
                          format: date-time
                        paid_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
        '401':
          description: Missing or invalid credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Credential lacks the MPS audit capability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Hourly credential rate limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Credential registry or ledger unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/mps-credits/checkout:
    post:
      tags:
      - Checkout
      operationId: createCreditCheckout
      summary: Start a prepaid credit-pack purchase
      description: Creates a dormant MPS-only credential and a Stripe Checkout session. The credential secret is returned once, here, and activates only after Stripe confirms payment via signed webhook.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - clientRequestId
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 254
                  description: Receipt email.
                clientRequestId:
                  type: string
                  minLength: 8
                  maxLength: 120
                  description: Caller-chosen request key, one line.
      responses:
        '201':
          description: Checkout prepared. Redirect the buyer to `checkoutUrl` and store `credential` now — it is never shown again.
          content:
            application/json:
              schema:
                type: object
                required:
                - checkoutId
                - checkoutUrl
                - credential
                - creditQuantity
                - unit
                - expiresAt
                properties:
                  checkoutId:
                    type: string
                    pattern: ^credit_checkout_[a-f0-9]{32}$
                  checkoutUrl:
                    type: string
                    format: uri
                    description: Stripe-hosted payment page.
                  credential:
                    type: string
                    description: One-time plaintext API credential (dormant until payment).
                  credentialPrefix:
                    type: string
                    pattern: ^mhaic_[A-Za-z0-9_-]{8}$
                  creditQuantity:
                    type: integer
                    minimum: 1
                  unit:
                    type: string
                    const: mps_audit_invocation
                  expiresAt:
                    type: string
                    format: date-time
                  secretDisclosure:
                    type: string
        '400':
          description: Invalid email or clientRequestId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '415':
          description: Content-Type must be application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: Stripe checkout could not be started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Checkout is not enabled or a backing service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable explanation.
  securitySchemes:
    credential:
      type: http
      scheme: bearer
      description: MPS client credential (`mhaic_…`), issued once at purchase.