Runtime API
The runtime API is how an integration asks Nodrail Cloud whether an agent may take an action, waits for a person when one must decide, and records what happened. The TypeScript SDK and the Claude Code and Codex plugins use it. Use it directly from any language that can send HTTPS requests.
Every path below is relative to this base URL:
https://app.nodrail.com/api/v1/runtime
The flow
- Submit the action the agent wants to take. Nodrail records it and decides it against your active rules.
- Wait while the answer is
APPROVAL_PENDINGorUNKNOWN_PERMISSION_BLOCKED, polling the action until a person decides or it expires. If you stop waiting first, withdraw the action. - Request a permit once the action is
READY. Only a permit response withcode: "ALLOW"clears the tool to run. - Run the tool, then report the outcome.
READY is not permission. Everything is checked again when you request the permit, against the rules and the run's history as they stand then.
Authentication
Every request sends the installation's credential as a bearer token and a JSON body:
Authorization: Bearer ndr_...
Content-Type: application/json
- Create a credential in Nodrail Cloud when you connect an agent. Each credential belongs to one installation of one agent.
- A request that carries any
Cookieheader is refused withUNAUTHENTICATED, so a browser session is never mistaken for an installation. Send requests from a server or a script, not from a browser. - Each installation can make 600 requests a minute.
Request bodies are strict: an unknown field is refused with INVALID_INPUT. A body may be at most 64 KB.
Submit an action
POST /actions
curl https://app.nodrail.com/api/v1/runtime/actions \
-H "Authorization: Bearer $NODRAIL_CREDENTIAL" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f6c1a52-9a0e-4d7c-9b1e-0b6f6b8d2c11" \
-d '{
"tool": "github",
"operation": "pulls.create",
"resource": { "kind": "repository", "id": "acme/app" },
"params": { "title": "Fix login", "base": "main" },
"run": { "key": "ENG-42", "step": { "id": "s-7", "agent": "github" } }
}'
| Field | Required | Meaning |
|---|---|---|
tool, operation | Yes | What the agent wants to do, as your rules name it. |
resource | Yes | { "kind", "id" }: what it acts on. id is at most 512 characters. |
params | Yes | A JSON object of the call's arguments, at most 32 KB. Send {} when there are none. Remove secrets first. |
run | No | The run the call belongs to: { "key" }, plus step: { "id", "agent" } when an agent's step makes it. Gates and budgets use it. A run belongs to the installation that sends it: another installation using the same key has a run of its own. Without run, every gate the action matches is unmet and every budget that covers it holds it. See Runs, gates and budgets (preview). |
adapter_version | No | Your integration's version, shown in Cloud. |
The Idempotency-Key header is required, 1 to 128 characters, unique per action. Sending the same key again returns the same action instead of creating a second one, so a retry after a timeout is safe. The same key with a different action is refused with IDEMPOTENCY_CONFLICT.
The answer is the action's status:
{
"code": "APPROVAL_PENDING",
"action_id": "9b2f0c1e-6a7d-4f39-8c55-2d1e7a4b9f03",
"installation_id": "…",
"permit_id": null,
"descriptor_digest": "sha256:…",
"action_digest": "sha256:…",
"reference": "…",
"reason": null,
"expires_at": "…"
}
code | Meaning | What to do |
|---|---|---|
READY | The rules allow it, or a person approved it. | Request a permit. |
APPROVAL_PENDING | A rule or gate asks a person to review it. | Poll the action. |
UNKNOWN_PERMISSION_BLOCKED | No rule covers it, so a person must decide. | Poll the action. |
DENIED | A rule, gate, budget or person denied it, or the agent is paused. | Don't run the tool. |
EXPIRED | Nobody decided in time. Reviews wait up to 60 minutes. | Don't run the tool; submit again if still needed. |
INVALIDATED | The approval no longer stands, for example the rules or the agent's access changed. | Don't run the tool. |
PERMIT_ISSUED | A permit was already issued for this action. | Don't run the tool a second time. |
reason says why, when there is more to say: rule, gate, budget, human or agent_paused for DENIED; for INVALIDATED, what changed, such as policy_changed, agent_paused, credential_revoked approver_access_removed, or withdrawn when your integration withdrew it.
Read an action
GET /actions/{action_id} returns the same status. Poll it while a person decides; the SDK polls every few seconds.
GET /actions?idempotency_key=KEY finds an action by the key you submitted it with, for when the submit's answer was lost.
Request a permit
POST /actions/{action_id}/permit
curl https://app.nodrail.com/api/v1/runtime/actions/$ACTION_ID/permit \
-H "Authorization: Bearer $NODRAIL_CREDENTIAL" \
-H "Content-Type: application/json" \
-d '{ "action_digest": "sha256:…", "nonce": "c2b7e0a14f9d4e7a8b1c" }'
action_digest: the one from the action's status. If the action is no longer the one you submitted, the request is refused withACTION_CHANGED.nonce: 16 to 128 random characters you generate. The permit echoes it asclaim_nonce; check that it matches.
The tool may run only when the answer is:
{
"code": "ALLOW",
"permit_id": "…",
"action_id": "…",
"action_digest": "sha256:…",
"installation_id": "…",
"claim_nonce": "c2b7e0a14f9d4e7a8b1c",
"policy_version_id": "…",
"access_epoch": 1,
"issued_at": "…",
"expires_at": "…"
}
A permit is valid for 5 seconds and is issued once per action; asking again is refused with PERMIT_ALREADY_ISSUED. Any other answer has a code from the status table and a reason, and the tool must not run. An action that was READY can still be refused here: for example, a builder agent started again since it was submitted, so a gate closed again.
Checking the digests
The SDK checks that the action it gets back is the one it sent before trusting it. To do the same in another language:
descriptor_digestissha256:followed by the hex SHA-256 of the JSON canonical form (RFC 8785) of{ "canonicalizer": 1, "installation": installation_id, "operation", "params", "resource", "schema": 1, "tool" }.action_digestissha256:followed by the hex SHA-256 of the textnodrail:action:v1, a newline, theaction_id, a newline and thedescriptor_digest.
The open-source reference implementation is @nodrail/policy-engine/protocol.
Withdraw an action
POST /actions/{action_id}/withdraw with {}
Call it when you stop waiting for a person before anyone decided, for example when your own deadline passes or the agent is interrupted. The request leaves the Approvals queue, so nobody approves something that will never run, and the action becomes INVALIDATED with reason: "withdrawn". A permit is refused for it from then on.
- Only the installation that submitted the action can withdraw it; for any other it is
NOT_FOUND. - It changes only a request still waiting for a person. Withdrawing again, or an action already decided, expired, closed or never waiting for anyone, changes nothing.
- It never allows anything.
- The answer is the action's status, as for
GET /actions/{action_id}.
Don't withdraw an action you mean to come back to: if you submit and check again later, leave it for a person to decide.
Report the outcome
POST /actions/{action_id}/reports
{
"report_key": "9b2f0c1e-report-1",
"outcome": "success",
"permit_id": "…",
"details": { "duration_ms": 412 }
}
outcome:success,failureorunknown.report_key: 1 to 128 characters; resending the same key records it once.details: optional JSON object, at most 8 KB. Don't send secrets or full tool output.
A report is recorded as your integration's word. It never changes a decision. The answer is { "recorded": true }.
Record a step
POST /steps
When an agent's step starts and finishes inside a run, record it so gates and budgets can use it:
{ "run": { "key": "ENG-42" }, "step": { "id": "s-6", "agent": "qa" }, "event": "started" }
{
"run": { "key": "ENG-42" },
"step": { "id": "s-6", "agent": "qa" },
"event": "finished",
"receipt": { "verdict": "pass", "findings": [], "usage": { "usd": 0.4 } }
}
step.idis yours: any id unique within the run.agentis the step's agent name.- The run is this installation's own, as for actions: a step another installation reports under the same key is in its run, never in yours, so it can't finish your steps or meet your gates.
- Send
startedbeforefinished. A step that finishes with no recorded start can't meet a gate, because Nodrail can't tell what work it saw. receiptis allowed only onfinished. Send the receipt read, as above, or the agent's receipt block as text,{ "text": "```nodrail-receipt\nverdict: pass\n```" }, at most 8 KB, for Nodrail to read.- A step that finishes without a receipt has no verdict, so gates waiting for it stay closed.
- Steps never use governed actions. Each new step uses one of the workspace's monthly run steps, as many as its plan has actions; past them, a new step is refused with
QUOTA_EXCEEDEDand is not recorded. Repeating an event, or finishing a step already recorded, uses none.
The answer is { "recorded": true }.
Heartbeat
POST /heartbeat with {} or { "adapter_version": "1.2.0" } marks the installation as connected in Cloud. Any other call does too.
Errors
Errors have one shape. Quote request_id when you contact support.
{ "error": { "code": "INVALID_INPUT", "request_id": "…" } }
| HTTP | code | Meaning |
|---|---|---|
| 401 | UNAUTHENTICATED | Missing, revoked or unknown credential, or the request carried a cookie. |
| 403 | FORBIDDEN | The credential can't do this. |
| 404 | NOT_FOUND | No such action for this installation. |
| 409 | IDEMPOTENCY_CONFLICT | The key was used for a different action, or the step already finished with a different receipt. |
| 409 | ACTION_CHANGED | The action_digest doesn't match the action. |
| 409 | PERMIT_ALREADY_ISSUED | This action already has its permit. |
| 409 | RUN_TOO_LONG | The run has 20,000 recorded steps and actions, more than one decision reads. Start a new run key; don't run the tool. |
| 402 | QUOTA_EXCEEDED | The workspace used its plan's governed actions, or for POST /steps its run steps, for the month. |
| 422 | INVALID_INPUT | The body, a header or a field is missing, too large or not allowed. |
| 429 | RATE_LIMITED | More than 600 requests a minute from this installation. Wait and retry. |
| 503 | UNAVAILABLE, BUSY | Try again shortly. |
On any error, network failure or answer you don't understand, don't run the tool. Nodrail fails closed, and your integration should too.