> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference: every endpoint

> Every operation of the Parmana REST API, grouped as in the API reference, generated from the OpenAPI file.

Every operation the server exposes, 59 in all, read from `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`](/api-reference/endpoints/execute-transaction) | Sends one action for a decision and, if approved, performs it. |

## Transactions

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/transactions`](/api-reference/endpoints/list-transactions) | Lists the Business Transactions your key submitted, as a bare array with no paging metadata. |
| `POST` | [`/transactions`](/api-reference/endpoints/create-transaction) | The same as `POST /execute` in every way except the success status, `201` instead of `200`. |
| `GET` | [`/transactions/{businessTransactionId}`](/api-reference/endpoints/get-transaction) | Returns one Business Transaction as it was stored. |

## Verification

| Method | Path | What it does |
| - | - | - |
| `POST` | [`/verify`](/api-reference/endpoints/verify-transaction) | Checks a Trust Record again on the server: recomputes its hash, verifies its signature and checks that every approved execution is bound to its authorization. |
| `GET` | [`/verification/{businessTransactionId}`](/api-reference/endpoints/get-latest-verification) | Returns the most recent Verification appended to a Trust Record by `POST /verify`. |

## Receipts

| Method | Path | What it does |
| - | - | - |
| `POST` | [`/receipt`](/api-reference/endpoints/generate-receipt) | Generates a signed Receipt for a Trust Record: a compact proof of what was decided and executed, to hand to a person or another system. |
| `GET` | [`/receipt/latest/{businessTransactionId}`](/api-reference/endpoints/get-latest-receipt) | Returns the most recent Receipt for a Trust Record. |

## Trust Records

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/trust-records`](/api-reference/endpoints/list-trust-records) | Exports your full, signed Trust Records (transaction, decision, executions, verifications, receipts) a page at a time, for audit and compliance. |
| `GET` | [`/trust-records/{businessTransactionId}`](/api-reference/endpoints/get-trust-record) | Returns the complete signed Execution Trust Record for a transaction: what was asked, what the policy decided, what was executed and the connector's answer, with signatures. |

## Replay

| Method | Path | What it does |
| - | - | - |
| `POST` | [`/replay`](/api-reference/endpoints/replay-transaction) | Verifies the stored signature on a Trust Record and returns its hash with the result. |

## Policies

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/policies/in-effect`](/api-reference/endpoints/get-policy-in-effect) | Tells an agent what a request for a capability must declare and carry right now: the policy name and version, the policy's description, and its signals (every fact the rules read with its type, the facts that must equal a value of the in... |
| `POST` | [`/policies/validate`](/api-reference/endpoints/validate-policy) | Checks that this server can load a policy at a name and version, the same lookup a request uses. |

## Policy Governance

| Method | Path | What it does |
| - | - | - |
| `POST` | [`/policies/{name}/{version}/pending-changes`](/api-reference/endpoints/propose-policy-change) | Proposes new content for a policy, the maker's step in maker checker governance. |
| `GET` | [`/policies/pending-changes`](/api-reference/endpoints/list-pending-policy-changes) | Lists policy changes with a diff: the content in effect today (`current`, or `null` for a new version) next to the proposed content. |
| `POST` | [`/policies/pending-changes/{id}/approve`](/api-reference/endpoints/approve-policy-change) | Approves a policy change, the checker's step, and puts it into effect. |
| `POST` | [`/policies/pending-changes/{id}/reject`](/api-reference/endpoints/reject-policy-change) | Rejects a policy change. |

## Approvers

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/approval-issuers`](/api-reference/endpoints/list-approval-issuers) | Lists every approver key the server trusts, or once trusted, to sign human approvals for policies that require one. |
| `GET` | [`/approval-issuers/changes`](/api-reference/endpoints/list-approval-issuer-changes) | Lists approver changes, newest first. |
| `POST` | [`/approval-issuers/changes`](/api-reference/endpoints/propose-approval-issuer-change) | Proposes trusting a new approver key (`add`, with its Ed25519 public key) or revoking one added this way (`revoke`). |
| `POST` | [`/approval-issuers/changes/{id}/approve`](/api-reference/endpoints/approve-approval-issuer-change) | Approves an approver change and applies it at once: an added key is trusted from the next approval checked; a revoked key's approvals are refused from the next request on, including ones it already signed. |
| `POST` | [`/approval-issuers/changes/{id}/reject`](/api-reference/endpoints/reject-approval-issuer-change) | Rejects an approver change. |

## External Connectors

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/external-connectors`](/api-reference/endpoints/list-external-connectors) | Lists every external connector registration, active and revoked: the capability, the HTTPS endpoint Parmana releases it to, the policy that governs it and the parameters forwarded. |
| `GET` | [`/external-connectors/changes`](/api-reference/endpoints/list-external-connector-changes) | Lists external connector changes, newest first. |
| `POST` | [`/external-connectors/changes`](/api-reference/endpoints/propose-external-connector-change) | Proposes connecting your own system to Parmana with no Parmana code change: `register` names a capability, the HTTPS endpoint to release it to, the policy that governs it, the parameters to forward and optionally a timeout; `revoke` ends... |
| `POST` | [`/external-connectors/changes/{id}/approve`](/api-reference/endpoints/approve-external-connector-change) | Approves an external connector change and applies it at once: `register` makes the registration active, `revoke` ends it. |
| `POST` | [`/external-connectors/changes/{id}/reject`](/api-reference/endpoints/reject-external-connector-change) | Rejects an external connector change. |

## Business Signal Sources

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/business-signal-sources`](/api-reference/endpoints/list-business-signal-sources) | Lists every business signal source registration, active and revoked: the name a policy's `signalSources` uses, the HTTPS endpoint Parmana asks, and the Ed25519 key its answers must be signed with, if one is registered. |
| `GET` | [`/business-signal-sources/changes`](/api-reference/endpoints/list-business-signal-source-changes) | Lists business signal source changes, newest first. |
| `POST` | [`/business-signal-sources/changes`](/api-reference/endpoints/propose-business-signal-source-change) | Proposes connecting a business system, any system that owns facts a policy needs (an ERP, an order system, a CRM, a ledger), so Parmana can ask it instead of trusting the agent's claim. |
| `POST` | [`/business-signal-sources/changes/{id}/approve`](/api-reference/endpoints/approve-business-signal-source-change) | Approves a business signal source change and applies it at once: `register` makes the registration active, so policies that name it can be evaluated; `revoke` ends it, so they are refused as `SOURCE_UNAVAILABLE`. |
| `POST` | [`/business-signal-sources/changes/{id}/reject`](/api-reference/endpoints/reject-business-signal-source-change) | Rejects a business signal source change. |

## Authority Grants

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/authority-grants`](/api-reference/endpoints/list-authority-grants) | Lists every authority grant, active and revoked: which caller may have which capability decided, within which limits, from when until when. |
| `GET` | [`/authority-grants/changes`](/api-reference/endpoints/list-authority-grant-changes) | Lists authority grant changes, newest first. |
| `POST` | [`/authority-grants/changes`](/api-reference/endpoints/propose-authority-grant-change) | Proposes per-agent authority (RFC-0023 phase 3): `grant` says the API key with `callerId` may have requests for `capability` decided, within `limits` on the request, until `validUntil` (at most 366 days); `revoke` ends the active grant. |
| `POST` | [`/authority-grants/changes/{id}/approve`](/api-reference/endpoints/approve-authority-grant-change) | Approves an authority grant change and applies it at once: `grant` makes the grant active, starting now unless it names a later `validFrom`; `revoke` ends it, so the caller's next request under a policy with `requireAuthorityGrant` is re... |
| `POST` | [`/authority-grants/changes/{id}/reject`](/api-reference/endpoints/reject-authority-grant-change) | Rejects an authority grant change. |

## Sandbox

| Method | Path | What it does |
| - | - | - |
| `POST` | [`/sandbox/approvals`](/api-reference/endpoints/create-sandbox-approval) | **Sandbox only.** Returns an approval signed by the sandbox's demo approver, so you can try an approved request from a browser. |

## Refusal Records

| Method | Path | What it does |
| - | - | - |
| `POST` | [`/refusal/verify`](/api-reference/endpoints/verify-refusal-record) | Checks a Refusal Record's signature. |
| `GET` | [`/refusal/{businessTransactionId}`](/api-reference/endpoints/get-refusal-record) | Returns the signed Refusal Record kept when a policy refused a transaction: the decision, the rule that refused, the facts it saw and the signature. |

## Execution Intents

| Method | Path | What it does |
| - | - | - |
| `POST` | [`/execution-intents/verify`](/api-reference/endpoints/verify-execution-intent) | Checks an Execution Intent's hash and signature. |
| `GET` | [`/execution-intents/unfinalized`](/api-reference/endpoints/list-unfinalized-execution-intents) | The operator's work queue: Execution Intents that never reached a signed Trust Record and were not closed by hand, oldest first. |
| `GET` | [`/execution-intents/{businessTransactionId}`](/api-reference/endpoints/get-execution-intent) | Returns the signed Execution Intent for a transaction and where it got to. |
| `POST` | [`/execution-intents/{businessTransactionId}/finalize`](/api-reference/endpoints/finalize-execution-intent) | Rebuilds the signed Trust Record for an action that was released but whose record was never produced, the repair for a `500` `EXECUTION_RECORD_INCOMPLETE`. |
| `POST` | [`/execution-intents/{businessTransactionId}/resolve`](/api-reference/endpoints/resolve-execution-intent) | Closes an intent in state `PREPARED` or `ERRORED` after a person checked the target system, the repair for a `502` `EXECUTION_OUTCOME_UNKNOWN`. |

## Audit

| Method | Path | What it does |
| - | - | - |
| `POST` | [`/audit/verify`](/api-reference/endpoints/verify-audit-event) | Checks the signature of a caller authentication audit event, the record the server keeps of every authentication, denial and governance action. |

## System

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/`](/api-reference/endpoints/get-root) | Returns the service name and `UP`. |
| `GET` | [`/health`](/api-reference/endpoints/get-health) | Liveness probe. |
| `GET` | [`/ready`](/api-reference/endpoints/get-ready) | Readiness probe. |
| `GET` | [`/openapi.yaml`](/api-reference/endpoints/get-open-api-spec) | This API's complete OpenAPI 3.1 document as YAML, self contained with no external references. |
| `GET` | [`/openapi.json`](/api-reference/endpoints/get-open-api-spec-json) | The same document as `GET /openapi.yaml`, as JSON, for tools and agents that expect a spec at a `.json` path. |
| `GET` | [`/api-manifest.json`](/api-reference/endpoints/get-api-manifest) | One index for agents and tools: where the OpenAPI document and the rendered references are, how to authenticate, and both official SDKs with their package name, registry and current version. |
| `GET` | [`/version`](/api-reference/endpoints/get-version) | Returns `name`, `version` and `api`. |
| `GET` | [`/keys/{keyId}`](/api-reference/endpoints/get-key) | Returns the public half of a signing key, so anyone can verify a Parmana signature without a Parmana account: "an auditor, a regulator, or an endpoint receiving a release. |
| `GET` | [`/.well-known/jwks.json`](/api-reference/endpoints/get-jwks) | Lists every public signing key this deployment can serve, the enumeration form of `GET /keys/{keyId}`. |
| `GET` | [`/callers/me`](/api-reference/endpoints/get-caller-me) | Returns who your key is and exactly what it may do: the caller id, the principals it may act for, the capabilities it may invoke and whether that includes every capability (`*`), after defaults are applied. |

## Handbook

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/parmana-handbook.pdf`](/api-reference/endpoints/get-handbook-pdf) | Downloads the Parmana Handbook as a PDF. |
| `GET` | [`/handbook/download-leads`](/api-reference/endpoints/get-handbook-download-lead) | Records an email address, then redirects to the handbook PDF. |
| `POST` | [`/handbook/download-leads`](/api-reference/endpoints/create-handbook-download-lead) | Records an email address and returns the handbook download link as JSON. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.