nodrail

Personal API

Preview reference. This API uses a personal access token to act on a workspace. To request an agent decision with an installation credential, use the Runtime API.

The personal API lets a person read and act on their Nodrail workspace from a script, a terminal or an assistant: the approval queue, Activity, runs, Insights and the rules file. The nodrail command line uses it. A Nodrail MCP server built on it is part of this preview and is not published yet.

npm i -g @nodrail/cli
nodrail login
nodrail approvals --watch

nodrail needs Node.js 22 or later. Its Cloud commands take a personal token. Its other commands work offline with no account: nodrail policy is the same as nodrail-policy, the command line of the open-source engine, and nodrail add manages a repository's playbooks (preview). See the CLI reference (nodrail).

It is not how agents are governed. Agents and their integrations use the Runtime API with an installation credential (ndr_…). This API takes a personal access token (ndp_…) instead, and each refuses the other's.

Every path below is relative to this base URL:

https://app.nodrail.com/api/v1

Who decides

Nodrail exists so that a person, not the agent, decides what an agent may do. A token that can approve requests lets whoever holds it approve them, so:

  • Never give a token with decide or rules:write to an agent that Nodrail governs. The agent could approve its own requests or rewrite the rules that hold it back. Give agents and assistants a read token.
  • A token acts as the person who created it, in one workspace, and never does more than their role allows now: role and membership are checked again on every request, so lowering a role or removing someone takes effect immediately.
  • Every decision or rules change made with a token is recorded as that person, "via API token name", and shows in Activity.
  • Always (allow once and add a rule) is not available through the API. Adding a rule goes through the rules file, which needs the rules:write scope.

Tokens

Create a token under your account → API tokens, the menu on your avatar. It is shown once; Nodrail keeps only a digest of it.

ScopeAllowsRole needed
readRead approvals, Activity, runs, Insights and the rules file. Always included.Any
decideApprove once or reject a waiting request.Approver or admin
rules:writePreview and publish the rules file, which also adds and removes rules.Policy manager or admin

decide and rules:write are off unless you choose them. A token expires after 30, 90 (the default) or 365 days, or never if you choose so, and you can revoke it at any time; admins can revoke anyone's. Removing a person from the workspace revokes their tokens.

Send it as a bearer token:

curl https://app.nodrail.com/api/v1/me \
  -H "Authorization: Bearer $NODRAIL_TOKEN"

  • A request that carries any Cookie header is refused with UNAUTHENTICATED, so a browser session is never mistaken for a token. Call the API from a script or a server, not from a browser.
  • Each token can make 120 requests a minute.
  • Request bodies are JSON and strict: an unknown field is refused with INVALID_INPUT. So are unknown query parameters and filter values. A body may be at most 256 KB.
  • Answers are JSON with snake_case fields. Fields that hold what an agent sent, parameters and details, are passed through as received: treat them as untrusted text.

Environments

Approvals, Activity, runs, Insights and rules belong to an environment. Add ?environment= and its slug, for example ?environment=production, to choose one; without it, the workspace's default environment is used. GET /me lists them.

Pagination

Lists answer { "items": [...], "next_cursor": "…" }. While next_cursor is not null, pass it back as ?cursor= with the same filters for the next page. limit sets the page size, from 1 to 100 (default 50).

Who am I

GET /me

{
  "token": {
    "id": "…",
    "name": "laptop",
    "prefix": "ndp_3f9a1c2b7e04",
    "scopes": ["read", "decide"],
    "created_at": "…",
    "expires_at": "…",
    "last_used_at": "…"
  },
  "person": { "name": "Ana Ruiz" },
  "workspace": { "id": "…", "name": "Acme", "slug": "acme" },
  "role": "approver",
  "can": { "read": true, "decide": true, "rules_write": false },
  "environments": [
    { "slug": "development", "name": "Development", "default": true },
    { "slug": "production", "name": "Production", "default": false }
  ]
}

can is what this token can do right now: its scopes, limited by your role.

Approvals

GET /approvals lists the requests waiting for a person, newest first, at most 100. Filter by agent with ?agent= and its key. Requests expire after 60 minutes, so the queue stays short; next_cursor is always null.

GET /approvals/{id} returns one request in any state.

{
  "id": "6d1c…",
  "reference": "APR-6D1C2F0A",
  "state": "pending",
  "reason": "new_permission",
  "created_at": "…",
  "expires_at": "…",
  "agent_key": "support-bot",
  "installation_name": "support-bot-prod",
  "environment": "Production",
  "tool_key": "github",
  "operation_key": "issues.delete",
  "resource_kind": "issue",
  "resource": "acme/support#482",
  "parameters": { "issue": 482 },
  "action_digest": "sha256:…",
  "attempts": 1,
  "asked_before": 0,
  "decided_at": null,
  "decided_by": null,
  "permit_issued": false,
  "run_id": null,
  "run_key": null,
  "hold": null,
  "invalidated_reason": null,
  "can_decide": true
}

state is pending, approved_once, denied, expired or invalidated. hold names the gate or budget that held the action, with the requirements it is missing. can_decide says whether this token can decide it now.

Decide

POST /approvals/{id}/decision needs the decide scope.

curl https://app.nodrail.com/api/v1/approvals/$ID/decision \
  -H "Authorization: Bearer $NODRAIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "allow_once", "expected_action_digest": "sha256:…" }'

  • decision: allow_once or deny.
  • expected_action_digest: the action_digest you were shown. If the request is no longer that action, it is refused with ACTION_CHANGED, so you never approve something you didn't see.

The answer is the request as decided. Deciding again the same way returns it unchanged; a different decision already made is DECISION_CONFLICT, and a request that expired or closed is APPROVAL_NOT_PENDING.

Activity

GET /activity lists events newest first, with the filters of the Activity page:

ParameterValues
qText to search: agent, installation, tool and operation, resource, reference, run, rule or person.
agentAn agent's key.
outcomeallowed, denied, held, waiting, expired or closed.
kinddecisions, reports or changes.
range24h, 7d or 30d.
runA run's id.
{
  "items": [
    {
      "id": "…",
      "occurred_at": "…",
      "code": "approval_allowed_once",
      "group": "decision",
      "outcome": "allowed",
      "label": "Allowed once",
      "actor": { "kind": "human", "name": "Ana Ruiz", "via": "laptop" },
      "agent_key": "support-bot",
      "action": {
        "tool_key": "github",
        "operation_key": "issues.delete",
        "resource_kind": "issue",
        "resource": "acme/support#482",
        "installation_name": "support-bot-prod",
        "approval_id": "…",
        "run": null,
        "reference": "APR-6D1C2F0A"
      },
      "environment": "Production",
      "rule": null,
      "closed_reason": null,
      "closed_requests": null,
      "subject": null,
      "detail": null,
      "latest_report": null
    }
  ],
  "next_cursor": "…"
}

actor.via is the name of the API token a person used, when they used one.

GET /activity/{id} returns one event with the action's parameters and the integration's reports.

Runs

GET /runs lists runs, the most recently active first. It takes q, agent, outcome and range as Activity does.

GET /runs/{id} returns one run with its timeline: steps starting and finishing, and actions, oldest first.

Insights

GET /insights?days=30 returns the numbers on the Insights page for the last 7, 30 (the default) or 90 days:

  • approvals: requests, approved, denied, expired, withdrawn, closed and waiting, the median and 90th percentile seconds to decide, and how many actions rules decided against people.
  • rules: the rules that decided most, those that decided nothing, and the share decided by rules.
  • repeated_approvals: permissions people allowed once at least 3 times and never denied, each one a rule you could add.

Rules

GET /rules returns the environment's active rules, gates and budgets as a rules file:

{ "environment": "development", "yaml": "version: 1\nrules:\n  …" }

Changing the rules takes two steps, as in the YAML editor, and both need the rules:write scope.

  1. POST /rules/preview with { "yaml": "…" } checks the file and says what publishing it would change: issues, warnings, added, changed, removed, unchanged, and the policy_revision and file_digest it was computed from. Preview changes nothing.
  2. POST /rules/publish with { "yaml": "…", "policy_revision": 12, "file_digest": "…" } from that preview makes the environment match the file, as one new version. If the file has issues it is refused with INVALID_INPUT; if the rules or the file changed since the preview, with RULE_CHANGED. Preview again and publish what you saw.

The publish answer is { "policy_revision", "added", "changed", "removed", "closed_requests" }. Waiting requests the new rules decide differently are closed, as when a rule changes on screen.

Errors

Errors have the shape of the Runtime API's. Quote request_id when you contact support.

{ "error": { "code": "INSUFFICIENT_SCOPE", "request_id": "…" } }

HTTPcodeMeaning
401UNAUTHENTICATEDMissing, revoked, expired or unknown token; you are no longer a member; or the request carried a cookie.
403INSUFFICIENT_SCOPEThe token doesn't have the scope this needs.
403FORBIDDENYour role can't do this.
404NOT_FOUNDNo such request, event, run or environment, or you can't see it.
409ACTION_CHANGEDThe request is no longer the action you were shown.
409DECISION_CONFLICTSomeone already decided it the other way.
409APPROVAL_NOT_PENDINGIt expired or was closed before you decided.
409RULE_CHANGEDThe rules or the file changed since the preview.
422INVALID_INPUTThe body, a field, a filter or a query parameter is missing, too large or not allowed.
429RATE_LIMITEDMore than 120 requests a minute with this token. Wait and retry.
503UNAVAILABLE, BUSYTry again shortly.