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
decideorrules:writeto an agent that Nodrail governs. The agent could approve its own requests or rewrite the rules that hold it back. Give agents and assistants areadtoken. - 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:writescope.
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.
| Scope | Allows | Role needed |
|---|---|---|
read | Read approvals, Activity, runs, Insights and the rules file. Always included. | Any |
decide | Approve once or reject a waiting request. | Approver or admin |
rules:write | Preview 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
Cookieheader is refused withUNAUTHENTICATED, 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_casefields. Fields that hold what an agent sent,parametersanddetails, 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_onceordeny.expected_action_digest: theaction_digestyou were shown. If the request is no longer that action, it is refused withACTION_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:
| Parameter | Values |
|---|---|
q | Text to search: agent, installation, tool and operation, resource, reference, run, rule or person. |
agent | An agent's key. |
outcome | allowed, denied, held, waiting, expired or closed. |
kind | decisions, reports or changes. |
range | 24h, 7d or 30d. |
run | A 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.
POST /rules/previewwith{ "yaml": "…" }checks the file and says what publishing it would change:issues,warnings,added,changed,removed,unchanged, and thepolicy_revisionandfile_digestit was computed from. Preview changes nothing.POST /rules/publishwith{ "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 withINVALID_INPUT; if the rules or the file changed since the preview, withRULE_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": "…" } }
| HTTP | code | Meaning |
|---|---|---|
| 401 | UNAUTHENTICATED | Missing, revoked, expired or unknown token; you are no longer a member; or the request carried a cookie. |
| 403 | INSUFFICIENT_SCOPE | The token doesn't have the scope this needs. |
| 403 | FORBIDDEN | Your role can't do this. |
| 404 | NOT_FOUND | No such request, event, run or environment, or you can't see it. |
| 409 | ACTION_CHANGED | The request is no longer the action you were shown. |
| 409 | DECISION_CONFLICT | Someone already decided it the other way. |
| 409 | APPROVAL_NOT_PENDING | It expired or was closed before you decided. |
| 409 | RULE_CHANGED | The rules or the file changed since the preview. |
| 422 | INVALID_INPUT | The body, a field, a filter or a query parameter is missing, too large or not allowed. |
| 429 | RATE_LIMITED | More than 120 requests a minute with this token. Wait and retry. |
| 503 | UNAVAILABLE, BUSY | Try again shortly. |