Choose your path

Find your goal in the table. Each row names one place to start, what you need before you begin, and the first command or request. If two rows seem to apply, do the earlier one first.

What do you want to do?

Your goal	Start here	You need	First step
Put Parmana in front of an AI agent’s actions, from TypeScript	TypeScript SDK quickstart	Node 20 or later, a Parmana API URL, an API key	`npm install @parmana/sdk`
Put Parmana in front of an AI agent’s actions, from Python	Python SDK quickstart	Python 3.10 or later, a Parmana API URL, an API key	`pip install parmana`
Integrate from any other language, or with a plain HTTP client	REST API introduction and Authentication	Any HTTP client, a Parmana API URL, an API key	`POST /execute` with a Bearer key
Let Parmana release approved actions to a system you already use (HubSpot, GitHub, Slack, Paytm)	Connectors overview	A running Parmana server with that connector’s credentials configured	Read the overview, then the connector’s page
Build a new connector for a system Parmana does not support yet	Add a connector then the Connector development guide	Node or Python, and the system’s API credentials	`npm install @parmana/connector-sdk` or `pip install parmana-connector-sdk`
Run Parmana yourself on your own machine	Local deployment	Node 24 or later	Follow the page top to bottom
Run Parmana in production	Production deployment and the Environment variable reference	A host that runs Node 24 or later or a container, a Postgres database (Supabase), signing keys	Follow the page top to bottom
Decide what an agent is allowed to do	Write your first policy	A running Parmana server	Copy the example policy and change one rule
Approve or reject a change to a policy	Policy governance	A human credential and a step up signing key	Read the page, then follow the approval steps
Check a record someone gave you, as an auditor, without trusting Parmana	Verify a trust record independently	The record and Parmana’s public key	Follow the page top to bottom
Understand why Parmana works this way before you commit	How Parmana thinks	Nothing	Read it, it is short
See one complete working flow from agent to a real payment provider	End to end: agent, Parmana, Paytm	A deployed Parmana and a Paytm staging account	Follow the page top to bottom

The three steps every integration does

Whatever language you use, an integration is these three steps, in this order.

Get a key. Every request carries Authorization: Bearer <your key>. Keys are issued by whoever runs the Parmana server. See Authentication.
Send the action for a decision. Describe what the agent wants to do as a Business Transaction and send it with POST /execute. Give it a fresh businessTransactionId (a UUID) every time, because that identifier is the idempotency key. See Idempotency and nonces.
Act on the answer, and only on the answer. Proceed only when the response is HTTP 200 and executions[0].decision.outcome is APPROVED. Treat everything else as “not authorized”. The next section lists every answer.

What each answer means, and what to do

You receive	Meaning	What to do
`200` and `decision.outcome` is `APPROVED`	Policy approved it, and the action was released to the connector. You get a signed Execution Trust Record.	Proceed. Keep the record.
`403` with code `POLICY_DENIED`	A policy rule said no. This is a final decision.	Do not proceed. Do not retry the same request.
`403` with no code	Your key is not allowed to assert that principal.	Fix the key’s permissions.
`403` with code `CAPABILITY_NOT_ALLOWED`	Your key is not allowed to invoke that action.	Fix the key’s capabilities.
`401`	The key is missing or wrong.	Fix the key.
`400`	The request is malformed.	Fix the request. See the error catalog.
`409`	That `businessTransactionId` was already used.	Do not send it again. Look up the existing record instead.
`429`	You are rate limited.	Wait for the time in the `Retry-After` header, then retry with a new `businessTransactionId`.
`503` with code `SIGNING_UNAVAILABLE`	Parmana could not sign evidence, so it refused before releasing the action. Nothing was executed.	Retry later with a new `businessTransactionId`.
`500` with code `EXECUTION_RECORD_INCOMPLETE`	The action was released, but its signed record could not be produced.	Do not resubmit under a new id. Reconcile with the connector and the execution audit events for that `businessTransactionId`.
Any other `5xx`, or no response	Parmana’s answer is unknown.	Treat it as not authorized. Never treat “could not reach Parmana” as “allowed”.

The full list, with the exact messages, is the error catalog.

Which SDK?

You use	Package	Current version	Install
TypeScript or JavaScript	`@parmana/sdk` on npm	1.1.3	`npm install @parmana/sdk`
Python	`parmana` on PyPI	1.1.5	`pip install parmana`
Python, and you verify records offline	`parmana` with the `verify` extra	1.1.5	`pip install "parmana[verify]"`
Another language	The REST API	Not applicable	Any HTTP client, see Other languages

Both SDKs never retry POST /execute for you. They only retry idempotent GET requests, so an SDK can never turn a single action into two.

For AI agents

If you are an AI agent, do not use this page to decide what to do. Follow Integrate Parmana: specification for AI agents exactly. It is written to be followed literally, one step at a time, with what to expect and what to do when the result is different. It also has the same answer table as above, in the order to apply it.

Not sure yet

Read How Parmana thinks, then the Quickstart. Both are short, and neither needs an account.

​What do you want to do?

​The three steps every integration does

​What each answer means, and what to do

​Which SDK?

​For AI agents

​Not sure yet