Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. By signing up you are subscribing to the APIs.io and API Evangelist
newsletters — you can unsubscribe from any issue. See our
Privacy Policy and Terms.
openapi: 3.2.0
info:
title: Maha Strategies MPS Free 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: Free Preflight
description: Rate-limited public demo, no credential required.
paths:
/api/audit:
post:
tags:
- Free Preflight
operationId: runFreePreflight
summary: Run a free, rate-limited audit preflight
description: No credential required. Limited per visitor per day; passages up to 6000 characters.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- text
properties:
text:
type: string
maxLength: 6000
description: Passage to audit.
responses:
'200':
description: Audit result.
content:
application/json:
schema:
$ref: '#/components/schemas/AuditResult'
'400':
$ref: '#/components/responses/FlatError'
'413':
$ref: '#/components/responses/FlatError'
'415':
$ref: '#/components/responses/FlatError'
'429':
$ref: '#/components/responses/FlatError'
'502':
$ref: '#/components/responses/FlatError'
'503':
$ref: '#/components/responses/FlatError'
components:
schemas:
AuditClaim:
type: object
required:
- excerpt
- tag
- rationale
- action
properties:
excerpt:
type: string
description: Verbatim excerpt from the passage (6–25 words).
tag:
type: string
enum:
- VERIFIED
- SOURCED
- BOUNDARY
- ILLUSTRATIVE
- UNVERIFIED
rationale:
type: string
maxLength: 1000
action:
type: string
enum:
- none
- verify
- cite
- reword
- remove
AuditResult:
type: object
required:
- mps_version
- input_hash
- claims
properties:
mps_version:
type: string
const: '0.1'
input_hash:
type: string
description: SHA-256 of the audited passage.
claims:
type: array
items:
$ref: '#/components/schemas/AuditClaim'
responses:
FlatError:
description: Error (free preflight uses a flat error string).
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
securitySchemes:
credential:
type: http
scheme: bearer
description: MPS client credential (`mhaic_…`), issued once at purchase.