# Personal API

> Read approvals, Activity, runs, Insights and rules, decide requests and publish rules with a personal access token, from scripts or a terminal.

> **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](https://nodrail.com/docs/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.

```sh
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)](https://nodrail.com/docs/playbooks). See the [CLI reference (nodrail)](https://nodrail.com/docs/cli).

It is not how agents are governed. Agents and their integrations use the [Runtime API](https://nodrail.com/docs/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:

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

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

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

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

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

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

| 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. |

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

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

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