mahastrategies-com Maha Celestial Evidence API

openapi: 3.2.0
info:
  title: Maha Strategies MPS Maha Celestial Evidence 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: Maha Celestial Evidence
  description: Tenant-scoped reproducible chart and evidence reports with explicit interpretive boundaries.
paths:
  /api/v1/calculations/positions:
    get:
      tags:
      - Maha Celestial Evidence
      operationId: describe-celestial-position-snapshot
      security: []
      summary: Free calculation contract discovery
      responses:
        '200':
          description: Status, limits, conventions and synthetic examples; no calculation performed.
        '400':
          description: Query parameters are not accepted.
    post:
      tags:
      - Maha Celestial Evidence
      operationId: celestial-position-snapshot
      security: []
      summary: Maha Celestial Calculations (available)
      description: 'Build an astronomy or astrology tool with seven classical-body geocentric longitudes at one UTC instant, Tropical and versioned Lahiri Sidereal frames, conventions and a deterministic receipt. Public or synthetic inputs only. No interpretations, forecasts or predictive certification. Request and result bodies are not stored. x402-only: API keys are rejected without consuming enterprise credits. Save the returned payload; no stored-result recovery after network loss.'
      x-maha-status: available
      x-maha-payable-in-production: true
      x-maha-price-base-units: '20000'
      x-maha-max-request-bytes: 2048
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                dataClass:
                  type: string
                  enum:
                  - public
                  - synthetic
                instantUtc:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                  description: Canonical UTC ISO instant with milliseconds, 1600–2099 inclusive; impossible dates rejected.
              required:
              - dataClass
              - instantUtc
            example:
              dataClass: synthetic
              instantUtc: '2000-01-01T12:00:00.000Z'
      responses:
        '200':
          description: Paid calculation payload with unsigned deterministic integrity receipt.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - version
                - offerId
                - inputDigest
                - result
                - conventions
                - boundaries
                - receiptDigest
                properties:
                  version:
                    const: maha-celestial-calculations/0.1
                  offerId:
                    const: celestial-position-snapshot
                  inputDigest:
                    type: string
                    pattern: ^sha256:[a-f0-9]{64}$
                  result:
                    type: object
                    additionalProperties: false
                    required:
                    - instantUtc
                    - ayanamsaDegrees
                    - positions
                    properties:
                      instantUtc:
                        type: string
                        pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        description: Canonical UTC ISO instant with milliseconds, 1600–2099 inclusive; impossible dates rejected.
                      ayanamsaDegrees:
                        type: number
                      positions:
                        type: array
                        minItems: 7
                        maxItems: 7
                        items:
                          type: object
                          additionalProperties: false
                          required:
                          - body
                          - tropicalLongitude
                          - siderealLongitude
                          properties:
                            body:
                              type: string
                              enum:
                              - Sun
                              - Moon
                              - Mercury
                              - Venus
                              - Mars
                              - Jupiter
                              - Saturn
                            tropicalLongitude:
                              type: number
                              minimum: 0
                              maximum: 360
                            siderealLongitude:
                              type: number
                              minimum: 0
                              maximum: 360
                  conventions:
                    type: object
                  boundaries:
                    type: array
                    items:
                      type: string
                  receiptDigest:
                    type: string
                    pattern: ^sha256:[a-f0-9]{64}$
          headers:
            PAYMENT-RESPONSE:
              schema:
                type: string
              description: Separate x402 settlement response.
        '400':
          description: Invalid input, query parameters or unsupported enterprise credential; no charge.
        '402':
          description: x402 payment challenge, not a delivered calculation.
          headers:
            PAYMENT-REQUIRED:
              schema:
                type: string
        '409':
          description: Payment already used.
        '413':
          description: Body exceeds 2,048 bytes.
        '415':
          description: Requires application/json.
        '422':
          description: Calculation unavailable for input; no charge.
        '429':
          description: Capacity unavailable; inspect payment status before retry.
        '502':
          description: Settlement contradicted by chain.
        '503':
          description: Offer withheld, disabled or payment infrastructure unavailable.
  /api/v1/calculations/chart:
    get:
      tags:
      - Maha Celestial Evidence
      operationId: describe-celestial-chart-evidence
      security: []
      summary: Free calculation contract discovery
      responses:
        '200':
          description: Status, limits, conventions and synthetic examples; no calculation performed.
        '400':
          description: Query parameters are not accepted.
    post:
      tags:
      - Maha Celestial Evidence
      operationId: celestial-chart-evidence
      security: []
      summary: Maha Celestial Calculations (available)
      description: 'Build a reproducible chart view: Tropical and Lahiri Sidereal positions, Sidereal whole-sign houses, mean nodes, geometric aspects and panchanga for one UTC chart. Includes limitations and a deterministic receipt. Public or synthetic inputs only. No interpretation, forecast or predictive certification; bodies are not stored. x402-only: API keys are rejected without consuming enterprise credits. Save the returned payload; no stored-result recovery after network loss.'
      x-maha-status: available
      x-maha-payable-in-production: true
      x-maha-price-base-units: '60000'
      x-maha-max-request-bytes: 2048
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                dataClass:
                  type: string
                  enum:
                  - public
                  - synthetic
                instantUtc:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                  description: Canonical UTC ISO instant with milliseconds, 1600–2099 inclusive; impossible dates rejected.
                latitudeDegrees:
                  type: number
                  minimum: -89.9
                  maximum: 89.9
                longitudeDegrees:
                  type: number
                  minimum: -180
                  maximum: 180
              required:
              - dataClass
              - instantUtc
              - latitudeDegrees
              - longitudeDegrees
            example:
              dataClass: synthetic
              instantUtc: '2000-01-01T12:00:00.000Z'
              latitudeDegrees: 0
              longitudeDegrees: 0
      responses:
        '200':
          description: Paid calculation payload with unsigned deterministic integrity receipt.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - version
                - offerId
                - inputDigest
                - result
                - conventions
                - boundaries
                - receiptDigest
                properties:
                  version:
                    const: maha-celestial-calculations/0.1
                  offerId:
                    const: celestial-chart-evidence
                  inputDigest:
                    type: string
                    pattern: ^sha256:[a-f0-9]{64}$
                  result:
                    type: object
                    additionalProperties: false
                    required:
                    - chart
                    - panchanga
                    properties:
                      chart:
                        type: object
                        required:
                        - version
                        - instantUtc
                        - placements
                        - houses
                        - aspects
                        - ascendant
                        - methodology
                      panchanga:
                        type: object
                        required:
                        - version
                        - tithi
                        - nakshatra
                        - yoga
                        - karana
                        - uncertainLimbs
                  conventions:
                    type: object
                  boundaries:
                    type: array
                    items:
                      type: string
                  receiptDigest:
                    type: string
                    pattern: ^sha256:[a-f0-9]{64}$
          headers:
            PAYMENT-RESPONSE:
              schema:
                type: string
              description: Separate x402 settlement response.
        '400':
          description: Invalid input, query parameters or unsupported enterprise credential; no charge.
        '402':
          description: x402 payment challenge, not a delivered calculation.
          headers:
            PAYMENT-REQUIRED:
              schema:
                type: string
        '409':
          description: Payment already used.
        '413':
          description: Body exceeds 2,048 bytes.
        '415':
          description: Requires application/json.
        '422':
          description: Calculation unavailable for input; no charge.
        '429':
          description: Capacity unavailable; inspect payment status before retry.
        '502':
          description: Settlement contradicted by chain.
        '503':
          description: Offer withheld, disabled or payment infrastructure unavailable.
  /api/v1/calculations/vimshottari:
    get:
      tags:
      - Maha Celestial Evidence
      operationId: describe-celestial-vimshottari-timing
      security: []
      summary: Free calculation contract discovery
      responses:
        '200':
          description: Status, limits, conventions and synthetic examples; no calculation performed.
        '400':
          description: Query parameters are not accepted.
    post:
      tags:
      - Maha Celestial Evidence
      operationId: celestial-vimshottari-timing
      security: []
      summary: Maha Celestial Calculations (available)
      description: 'Build a Vimshottari timing display with birth balance, nine mahadashas and nine antardashas of the active mahadasha at a reference instant. Uses actual nakshatra stay time and a 365.2425-day year; includes conventions and receipt. Public or synthetic inputs only. No event prediction or interpretation; bodies are not stored. x402-only: API keys are rejected without consuming enterprise credits. Save the returned payload; no stored-result recovery after network loss.'
      x-maha-status: available
      x-maha-payable-in-production: true
      x-maha-price-base-units: '120000'
      x-maha-max-request-bytes: 2048
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                dataClass:
                  type: string
                  enum:
                  - public
                  - synthetic
                instantUtc:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                  description: Canonical UTC ISO instant with milliseconds, 1600–2099 inclusive; impossible dates rejected.
                latitudeDegrees:
                  type: number
                  minimum: -89.9
                  maximum: 89.9
                longitudeDegrees:
                  type: number
                  minimum: -180
                  maximum: 180
                referenceInstantUtc:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                  description: At or after instantUtc and less than 100 × 365.2425 days later, also within 1600–2099.
              required:
              - dataClass
              - instantUtc
              - latitudeDegrees
              - longitudeDegrees
              - referenceInstantUtc
            example:
              dataClass: synthetic
              instantUtc: '2000-01-01T12:00:00.000Z'
              latitudeDegrees: 0
              longitudeDegrees: 0
              referenceInstantUtc: '2026-01-01T12:00:00.000Z'
      responses:
        '200':
          description: Paid calculation payload with unsigned deterministic integrity receipt.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - version
                - offerId
                - inputDigest
                - result
                - conventions
                - boundaries
                - receiptDigest
                properties:
                  version:
                    const: maha-celestial-calculations/0.1
                  offerId:
                    const: celestial-vimshottari-timing
                  inputDigest:
                    type: string
                    pattern: ^sha256:[a-f0-9]{64}$
                  result:
                    type: object
                    additionalProperties: false
                    required:
                    - referenceInstantUtc
                    - vimshottari
                    properties:
                      referenceInstantUtc:
                        type: string
                        pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                        description: Canonical UTC ISO instant with milliseconds, 1600–2099 inclusive; impossible dates rejected.
                      vimshottari:
                        type: object
                        required:
                        - system
                        - birthNakshatraIngressUtc
                        - birthNakshatraEgressUtc
                        - balanceMethod
                        - balanceAtBirthYears
                        - yearLengthDays
                        - mahadashas
                        - antardashas
                        - activeMahadasha
                        - activeAntardasha
                        properties:
                          system:
                            const: vimshottari-120-year
                          yearLengthDays:
                            const: 365.2425
                          mahadashas:
                            type: array
                            minItems: 9
                            maxItems: 9
                          antardashas:
                            type: array
                            minItems: 9
                            maxItems: 9
                  conventions:
                    type: object
                  boundaries:
                    type: array
                    items:
                      type: string
                  receiptDigest:
                    type: string
                    pattern: ^sha256:[a-f0-9]{64}$
          headers:
            PAYMENT-RESPONSE:
              schema:
                type: string
              description: Separate x402 settlement response.
        '400':
          description: Invalid input, query parameters or unsupported enterprise credential; no charge.
        '402':
          description: x402 payment challenge, not a delivered calculation.
          headers:
            PAYMENT-REQUIRED:
              schema:
                type: string
        '409':
          description: Payment already used.
        '413':
          description: Body exceeds 2,048 bytes.
        '415':
          description: Requires application/json.
        '422':
          description: Calculation unavailable for input; no charge.
        '429':
          description: Capacity unavailable; inspect payment status before retry.
        '502':
          description: Settlement contradicted by chain.
        '503':
          description: Offer withheld, disabled or payment infrastructure unavailable.
  /api/v1/celestial/reports:
    post:
      tags:
      - Maha Celestial Evidence
      operationId: createCelestialReport
      summary: Compile a versioned individual or corporate celestial report
      security:
      - credential: []
      description: Requires a consent-record digest and explicit retention policy. Saved reports are tenant-isolated and application-encrypted. Interpretive provenance is not evidence of predictive validity.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CelestialReportRequest'
      responses:
        '201':
          description: Completed report and reproducibility bundle.
        '400':
          description: Invalid report input, consent, retention, or pack.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Organization role lacks report creation permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Idempotency key conflicts with another request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Credential retention policy conflicts with the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/celestial/reports/{reportId}:
    get:
      tags:
      - Maha Celestial Evidence
      operationId: getCelestialReport
      summary: Read an unexpired saved report
      security:
      - credential: []
      parameters:
      - name: reportId
        in: path
        required: true
        schema:
          type: string
          pattern: ^celrep_[a-f0-9]{24}$
      responses:
        '200':
          description: Decrypted report for the authenticated tenant.
        '403':
          description: Role lacks read permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Report absent, expired, or deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    delete:
      tags:
      - Maha Celestial Evidence
      operationId: deleteCelestialReport
      summary: Redact a saved report immediately
      security:
      - credential: []
      parameters:
      - name: reportId
        in: path
        required: true
        schema:
          type: string
          pattern: ^celrep_[a-f0-9]{24}$
      responses:
        '200':
          description: Ciphertext redacted and deletion tombstone recorded.
        '403':
          description: Role lacks deletion permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Report absent or already deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/celestial/reports/{reportId}/export:
    get:
      tags:
      - Maha Celestial Evidence
      operationId: exportCelestialReport
      summary: Export report evidence as canonical JSON or summary PDF
      security:
      - credential: []
      parameters:
      - name: reportId
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - pdf
          default: json
      responses:
        '200':
          description: Evidence export.
        '403':
          description: Role lacks export permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Report absent, expired, or deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/celestial/batches:
    post:
      tags:
      - Maha Celestial Evidence
      operationId: createCelestialBatch
      summary: Compile up to 25 isolated reports as one durable batch
      security:
      - credential: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - clientRequestId
              - requests
              properties:
                clientRequestId:
                  type: string
                  minLength: 8
                  maxLength: 96
                requests:
                  type: array
                  minItems: 1
                  maxItems: 25
                  items:
                    $ref: '#/components/schemas/CelestialReportRequest'
      responses:
        '200':
          description: Completed, partially failed, or failed batch manifest.
        '400':
          description: Invalid batch request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Role lacks batch permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/celestial/packs:
    get:
      tags:
      - Maha Celestial Evidence
      operationId: listCelestialPacks
      summary: List frozen interpretation-pack versions and digests
      security:
      - credential: []
      responses:
        '200':
          description: Immutable pack manifests.
        '403':
          description: Role lacks report access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    post:
      tags:
      - Maha Celestial Evidence
      operationId: installCelestialPack
      summary: Install one frozen interpretation-pack version for the tenant
      security:
      - credential: []
      responses:
        '200':
          description: Installed pack entitlement.
        '400':
          description: Pack unavailable for report type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Role lacks pack installation permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/celestial/webhooks:
    get:
      tags:
      - Maha Celestial Evidence
      operationId: listCelestialWebhooks
      summary: List tenant webhook endpoints without secrets
      security:
      - credential: []
      responses:
        '200':
          description: Sanitized endpoints.
        '403':
          description: Role lacks webhook permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    post:
      tags:
      - Maha Celestial Evidence
      operationId: registerCelestialWebhook
      summary: Register a signed public HTTPS webhook
      security:
      - credential: []
      responses:
        '201':
          description: Endpoint and one-time signing secret.
        '400':
          description: Unsafe URL or unsupported event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Role lacks webhook permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/celestial/usage:
    get:
      tags:
      - Maha Celestial Evidence
      operationId: getCelestialUsage
      summary: Summarize tenant report units and bytes
      security:
      - credential: []
      responses:
        '200':
          description: Auditable usage by operation.
        '403':
          description: Role lacks usage permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/celestial/service:
    get:
      tags:
      - Maha Celestial Evidence
      operationId: getCelestialServicePolicy
      summary: Read reproducibility, service objectives, and customer-safe incidents
      security:
      - credential: []
      responses:
        '200':
          description: Service policy and incidents.
        '403':
          description: Role lacks incident permission.
          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.
    CelestialReportRequest:
      type: object
      required:
      - apiVersion
      - clientRequestId
      - reportType
      - interpretationPack
      - dataPolicy
      - input
      additionalProperties: false
      properties:
        apiVersion:
          type: string
          const: maha-celestial-api/1
        clientRequestId:
          type: string
          minLength: 8
          maxLength: 96
        reportType:
          type: string
          enum:
          - individual-birth
          - corporate-event
        interpretationPack:
          type: object
          required:
          - packId
          - version
          properties:
            packId:
              type: string
              enum:
              - facts-only
              - jyotisha-source-bound
              - comparative-natal
            version:
              type: string
        dataPolicy:
          type: object
          description: Explicit consent basis, consent-record SHA-256 digest, save decision, and bounded retention.
        input:
          type: object
          description: BirthInput or CorporateReportInput as selected by reportType.
  securitySchemes:
    credential:
      type: http
      scheme: bearer
      description: MPS client credential (`mhaic_…`), issued once at purchase.