nodrail

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

  1. Submit the action the agent wants to take. Nodrail records it and decides it against your active rules.
  2. Wait while the answer is APPROVAL_PENDING or UNKNOWN_PERMISSION_BLOCKED, polling the action until a person decides or it expires. If you stop waiting first, withdraw the action.
  3. Request a permit once the action is READY. Only a permit response with code: "ALLOW" clears the tool to run.
  4. 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 Cookie header is refused with UNAUTHENTICATED, 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" } }
  }'

FieldRequiredMeaning
tool, operationYesWhat the agent wants to do, as your rules name it.
resourceYes{ "kind", "id" }: what it acts on. id is at most 512 characters.
paramsYesA JSON object of the call's arguments, at most 32 KB. Send {} when there are none. Remove secrets first.
runNoThe 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_versionNoYour 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": "…"
}

codeMeaningWhat to do
READYThe rules allow it, or a person approved it.Request a permit.
APPROVAL_PENDINGA rule or gate asks a person to review it.Poll the action.
UNKNOWN_PERMISSION_BLOCKEDNo rule covers it, so a person must decide.Poll the action.
DENIEDA rule, gate, budget or person denied it, or the agent is paused.Don't run the tool.
EXPIREDNobody decided in time. Reviews wait up to 60 minutes.Don't run the tool; submit again if still needed.
INVALIDATEDThe approval no longer stands, for example the rules or the agent's access changed.Don't run the tool.
PERMIT_ISSUEDA 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 with ACTION_CHANGED.
  • nonce: 16 to 128 random characters you generate. The permit echoes it as claim_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_digest is sha256: 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_digest is sha256: followed by the hex SHA-256 of the text nodrail:action:v1, a newline, the action_id, a newline and the descriptor_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, failure or unknown.
  • 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.id is yours: any id unique within the run. agent is 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 started before finished. A step that finishes with no recorded start can't meet a gate, because Nodrail can't tell what work it saw.
  • receipt is allowed only on finished. 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_EXCEEDED and 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": "…" } }

HTTPcodeMeaning
401UNAUTHENTICATEDMissing, revoked or unknown credential, or the request carried a cookie.
403FORBIDDENThe credential can't do this.
404NOT_FOUNDNo such action for this installation.
409IDEMPOTENCY_CONFLICTThe key was used for a different action, or the step already finished with a different receipt.
409ACTION_CHANGEDThe action_digest doesn't match the action.
409PERMIT_ALREADY_ISSUEDThis action already has its permit.
409RUN_TOO_LONGThe run has 20,000 recorded steps and actions, more than one decision reads. Start a new run key; don't run the tool.
402QUOTA_EXCEEDEDThe workspace used its plan's governed actions, or for POST /steps its run steps, for the month.
422INVALID_INPUTThe body, a header or a field is missing, too large or not allowed.
429RATE_LIMITEDMore than 600 requests a minute from this installation. Wait and retry.
503UNAVAILABLE, BUSYTry 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.