mahastrategies-com Governed Workflow API

openapi: 3.2.0
info:
  title: Maha Strategies MPS Governed Workflow 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: Governed Workflow
  description: Read-only evaluation prototype over a synthetic document-approval workflow. Stateless, metadata-only, and performs no side effect.
paths:
  /api/governed-workflow/demo:
    get:
      tags:
      - Governed Workflow
      operationId: getGovernedWorkflowScenario
      summary: List or replay a synthetic governed-workflow scenario
      description: 'Returns the frozen synthetic scenario catalog, or the sanitized transition timeline for one scenario. Evaluation prototype over an invented claims-review corpus: no real claim, document, reviewer, or payment is involved, and responses carry references, digests and bounded classifications only.'
      parameters:
      - name: scenario
        in: query
        required: false
        schema:
          type: string
        description: Scenario id. Omit to list the catalog, operations and schema paths.
      responses:
        '200':
          description: Scenario catalog, or one sanitized timeline.
          content:
            application/json:
              schema:
                type: object
                properties:
                  synthetic:
                    const: true
                  notice:
                    type: string
                  scenarioId:
                    type: string
                  finalState:
                    type: string
                  recovery:
                    type: object
                  timeline:
                    type: array
                    items:
                      type: object
        '404':
          description: Unknown scenario id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    post:
      tags:
      - Governed Workflow
      operationId: runGovernedWorkflowProgram
      summary: Run a governed-workflow demo program against the synthetic corpus
      description: Executes an ordered program of governed-workflow operations against an engine that exists only for the request. Nothing is stored, no side effect is performed, and the clock is fixed so the same program always returns the same digests. Evidence is selected from the synthetic catalog by name; a payload carrying document content is rejected rather than stripped.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - program
              properties:
                program:
                  type: array
                  minItems: 1
                  maxItems: 24
                  items:
                    type: object
                    required:
                    - operation
                    properties:
                      operation:
                        type: string
                        enum:
                        - create_workflow
                        - submit_evidence
                        - evaluate_policy
                        - request_approval
                        - record_approval
                        - authorize_action
                        - replay_recover
                        - audit_timeline
                      evidence:
                        type: array
                        items:
                          type: string
                          enum:
                          - claim_form
                          - policy_document
                          - assessment_note
                          - claim_form_revised
                      uncertainties:
                        type: array
                        items:
                          type: string
                          enum:
                          - missing_assessment
                          - minor_ambiguity
                      intendedState:
                        type: string
                      idempotencyKey:
                        type: string
                        maxLength: 120
                      action:
                        type: boolean
                      decision:
                        type: string
                        enum:
                        - grant
                        - deny
      responses:
        '200':
          description: 'Sanitized program result: per-step outcomes, the metadata-only timeline, chain integrity and recovery classification.'
          content:
            application/json:
              schema:
                type: object
                required:
                - schemaVersion
                - synthetic
                - notice
                - steps
                - finalState
                - timeline
                - chainIntegrity
                - recovery
                properties:
                  schemaVersion:
                    type: string
                  synthetic:
                    const: true
                  notice:
                    type: string
                  steps:
                    type: array
                    items:
                      type: object
                  finalState:
                    type: string
                  timeline:
                    type: array
                    items:
                      type: object
                  chainIntegrity:
                    type: object
                  recovery:
                    type: object
        '400':
          description: Invalid program, or a payload carrying document content rather than metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: Request exceeds the 16 KB demo program limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '415':
          description: Content-Type must be application/json.
          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.