# Runtime API

> Call Nodrail Cloud over HTTPS from any language: submit an action, wait for review, ask for a permit, report the outcome and record steps.

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:

```text
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:

```http
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`

```sh
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)](https://nodrail.com/docs/runs). |
| `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:

```json
{
  "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`

```sh
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:

```json
{
  "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)](https://www.rfc-editor.org/rfc/rfc8785) 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`

```json
{
  "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:

```json
{ "run": { "key": "ENG-42" }, "step": { "id": "s-6", "agent": "qa" }, "event": "started" }
```

```json
{
  "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.

```json
{ "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.
