openapi/openapi.bundled.yaml. Tests keep that file equal to the routes the server actually mounts (openapi-route-parity.test.ts). Each row links to the operation’s page, with its schemas and real captured responses.
Execution
| Method | Path | What it does |
|---|---|---|
POST | /execute | Runs the complete pipeline synchronously and returns the finished Execution Trust Record. |
Transactions
| Method | Path | What it does |
|---|---|---|
GET | /transactions | Returns every accepted Business Transaction. |
POST | /transactions | Identical to POST /execute in every way except the success status: this endpoint returns 201 where POST /execute returns 200. |
GET | /transactions/{businessTransactionId} | Returns a bare Business Transaction by ID. |
Verification
| Method | Path | What it does |
|---|---|---|
POST | /verify | Deterministically re-validates the complete Execution Trust Record for businessTransactionId: recomputed hash vs. |
GET | /verification/{businessTransactionId} | Returns the most recent Verification for the Execution Trust Record identified by businessTransactionId. |
Receipts
| Method | Path | What it does |
|---|---|---|
POST | /receipt | Generates a cryptographically signed Receipt for businessTransactionId. |
GET | /receipt/latest/{businessTransactionId} | Returns the most recent Receipt for the Execution Trust Record identified by businessTransactionId. |
Trust Records
| Method | Path | What it does |
|---|---|---|
GET | /trust-records | Returns the full, signed Execution Trust Record (transaction, executions, verifications, receipts, authorization) for every transaction on the requested page — the periodic full-export capability for external audit/compliance review, di… |
GET | /trust-records/{businessTransactionId} | Returns the complete Execution Trust Record for businessTransactionId (looked up by Business Transaction ID, despite the path segment name; there is no separate trustRecordId lookup). |
Replay
| Method | Path | What it does |
|---|---|---|
POST | /replay | Re-verifies the stored signature on the Execution Trust Record for businessTransactionId and returns its hash alongside the verification result. |
Policies
| Method | Path | What it does |
|---|---|---|
GET | /policies/in-effect | Returns the policy bound to a capability and the version a request for it must declare right now. |
POST | /policies/validate | Checks that policies///policy.json exists and parses. |
Policy Governance
| Method | Path | What it does |
|---|---|---|
POST | /policies/{name}/{version}/pending-changes | Proposes a change to a policy’s content (Policy Governance, maker-checker). |
GET | /policies/pending-changes | Lists Pending Policy Changes, each alongside a diff view: current (the live content at (policyName, policyVersion) today, or null if that version has never been published) and proposed (the change’s own proposedContent). |
POST | /policies/pending-changes/{id}/approve | Approves a Pending Policy Change (checker). |
POST | /policies/pending-changes/{id}/reject | Rejects a Pending Policy Change (checker). |
Approvers
| Method | Path | What it does |
|---|---|---|
GET | /approval-issuers | Every approver key the server trusts, or trusted, to sign approvals for policies that declare approvalSignals. |
GET | /approval-issuers/changes | Approver changes, newest first, optionally filtered by status. |
POST | /approval-issuers/changes | Proposes adding an approver key (action add, with the approver Ed25519 public key) or revoking a key added this way (action revoke). |
POST | /approval-issuers/changes/{id}/approve | Approves an approver change and applies it in one step: add trusts the key from the next approval checked, revoke refuses every approval the key ever signed from the next request on. |
POST | /approval-issuers/changes/{id}/reject | Rejects an approver change. |
External Connectors
| Method | Path | What it does |
|---|---|---|
GET | /external-connectors | Every external connector registration (ADR-0013), active and revoked: the capability, the HTTPS endpoint Parmana releases it to, the policy that governs it, and the parameters Parmana forwards. |
GET | /external-connectors/changes | External connector changes, newest first, optionally filtered by status. |
POST | /external-connectors/changes | Proposes registering an external connector (action register: a capability, the HTTPS endpoint to release it to, the policy that governs it, the parameters to forward, and optionally a timeout) or revoking the active one for a capability … |
POST | /external-connectors/changes/{id}/approve | Approves an external connector change and applies it in one step: register makes the registration active, revoke ends it. |
POST | /external-connectors/changes/{id}/reject | Rejects an external connector change. |
Refusal Records
| Method | Path | What it does |
|---|---|---|
POST | /refusal/verify | Verifies a Refusal Record’s signature (RFC-0021). |
GET | /refusal/{businessTransactionId} | Looks up a Refusal Record by businessTransactionId from Parmana’s own storage. |
Execution Intents
| Method | Path | What it does |
|---|---|---|
POST | /execution-intents/verify | Verifies an Execution Intent’s hash and signature (ADR-0012). |
GET | /execution-intents/unfinalized | Lists Execution Intents that never reached a signed Execution Trust Record and were not closed by hand, oldest first (ADR-0012). |
GET | /execution-intents/{businessTransactionId} | Returns the signed Execution Intent for a businessTransactionId and its operational status (ADR-0012). |
POST | /execution-intents/{businessTransactionId}/finalize | Rebuilds the signed Execution Trust Record for an action that was released but whose record was never produced (ADR-0012). |
POST | /execution-intents/{businessTransactionId}/resolve | Closes an Execution Intent in state PREPARED or ERRORED after a verified human reconciled it at the connector (G-54). |
Audit
| Method | Path | What it does |
|---|---|---|
POST | /audit/verify | Verifies a signed caller-authentication audit event’s signature, the same unauthenticated, third-party-verifiable capability as POST /refusal/verify, over the durable caller_audit_events audit trail instead of Refusal Records. |
System
| Method | Path | What it does |
|---|---|---|
GET | / | Minimal liveness response. |
GET | /health | Returns the operational health of the Parmana service. |
GET | /ready | Readiness probe, distinct from GET /health’s pure liveness check: when storage is Supabase-backed, this one actually queries Postgres (SELECT 1, no table rows transferred) so an orchestrator can tell a process that is up but backed by de… |
GET | /openapi.yaml | Serves the bundled, self-contained OpenAPI document (openapi/openapi.bundled.yaml, produced by npm run bundle:openapi from openapi/openapi.yaml + schemas/*.json) as a static file, see packages/api/src/routes/openapi.ts. |
GET | /openapi.json | The same bundled spec as GET /openapi.yaml, JSON-serialized instead of YAML, see packages/api/src/routes/openapi-json.ts. |
GET | /api-manifest.json | A single machine-readable index for coding agents and tooling: the OpenAPI spec locations, the rendered documentation views, the authentication scheme, and both official SDKs (TypeScript and Python) with their real, current package name,… |
GET | /version | Returns hardcoded deployment identifiers. |
GET | /keys/{keyId} | Deliberately unauthenticated, like GET /audit/verify and GET /refusal/verify. |
GET | /.well-known/jwks.json | Same unauthenticated, third-party-verification purpose as GET /keys/, this is the enumeration form. |
GET | /callers/me | The proof artifact a security review asks for: “show me this agent’s identity and exactly what it’s authorized to do.” Read-only, self-lookup only, an authenticated caller sees its own record, never another caller’s, and this never retur… |
Handbook
| Method | Path | What it does |
|---|---|---|
GET | /parmana-handbook.pdf | Serves the handbook PDF (docs/site/parmana-handbook.pdf, generated by scripts/generate-handbook-pdf.ts from docs/site/handbook/*.mdx) as a static file directly from this API, see packages/api/src/routes/handbook-pdf.ts. |
GET | /handbook/download-leads | Backs the plain-HTML-form download at docs/site/handbook/download.mdx — a GET so a <form method="get"> with no client-side JavaScript can submit it directly, since the docs site host may sandbox or strip inline <script> tags. |
POST | /handbook/download-leads | Backs a programmatic caller that wants a downloadUrl back in a JSON response body instead of a redirect — see GET /handbook/download-leads above for the browser-form variant, which is what the actual docs site page uses. |