mahastrategies-com Evidence Preflight API

openapi: 3.2.0
info:
  title: Maha Strategies MPS Evidence Preflight 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: Evidence Preflight
  description: Deterministic structural triage for caller-supplied claim, source, excerpt, locator, and rights metadata. No source inspection or verification is performed.
paths:
  /api/evidence-preflight:
    post:
      tags:
      - Evidence Preflight
      operationId: runEvidencePreflight
      summary: Run deterministic structural evidence preflight for up to three claims
      description: No credential required. Assesses only the structure and bounded lexical risk of caller-supplied material. Sources are not fetched or independently inspected; findings are not verified Evidence Dossiers. Submission content is returned in the response but not retained. A keyed metadata-only ledger enforces replay safety and a daily visitor limit.
      security:
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - requestId
              - submissionConfirmedNonConfidential
              - claims
              properties:
                requestId:
                  type: string
                  pattern: ^epf_[a-z0-9-]{16,80}$
                submissionConfirmedNonConfidential:
                  type: boolean
                  const: true
                claims:
                  type: array
                  minItems: 1
                  maxItems: 3
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - claim
                    - source
                    - rights
                    properties:
                      claim:
                        type: string
                        minLength: 8
                        maxLength: 1000
                      source:
                        type: object
                        additionalProperties: false
                        required:
                        - kind
                        - identifier
                        properties:
                          kind:
                            type: string
                            enum:
                            - doi
                            - url
                          identifier:
                            type: string
                            minLength: 4
                            maxLength: 500
                          title:
                            type: string
                            maxLength: 300
                          publisher:
                            type: string
                            maxLength: 200
                          publicationDate:
                            type: string
                            format: date
                      excerpt:
                        type: string
                        maxLength: 1500
                      locator:
                        type: object
                        additionalProperties: false
                        required:
                        - kind
                        - value
                        properties:
                          kind:
                            type: string
                            enum:
                            - page
                            - section
                            - paragraph
                            - figure
                            - table
                            - equation
                            - timestamp
                            - other
                          value:
                            type: string
                            maxLength: 160
                      rights:
                        type: object
                        additionalProperties: false
                        required:
                        - basis
                        - accessStatus
                        properties:
                          basis:
                            type: string
                            enum:
                            - public-domain
                            - open-license
                            - permission-confirmed
                            - limited-quotation-review
                            - unknown
                          accessStatus:
                            type: string
                            enum:
                            - open
                            - restricted
                            - unknown
                          licenseOrPermission:
                            type: string
                            maxLength: 240
      responses:
        '200':
          description: Idempotent replay of the same request ID and content.
        '201':
          description: Digest-bound automated structural preflight result. No source was independently inspected.
        '400':
          description: Invalid or disallowed submission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Request origin is not permitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Request ID was already used with different content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: Request exceeds 24 KB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '415':
          description: Content-Type must be application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Daily free preflight limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Privacy ledger or required server configuration 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.