REST API

Everything the dashboard does goes through the REST API at https://flag.nightroll.app/api/v1. Paths below are relative to it; {org} is your org’s slug (or id) and must be the org your key belongs to.

Authentication

Send an API key as a bearer token:

curl https://flag.nightroll.app/api/v1/orgs/$ORG/projects/default/flags \
  -H "Authorization: Bearer nr_flag_..."

Make keys under Settings → API keys. A key is bound to one org, acts with your role there, and is limited by its scopes:

A key (or an MCP client connected with OAuth) acts as an agent: its changes to a critical environment become change requests unless an admin turns that off in the dashboard’s Settings, and it can never review a change request. GET /me shows who and which org a key is for.

The dashboard uses a session cookie; state-changing cookie requests must come from Flag’s own origin.

Errors

Errors are JSON with a stable code and a message written for people:

{"error": {"code": "conflict", "message": "Flag new-checkout already exists in default."}}

Dry runs

Every mutation accepts ?dryRun=true: it runs in a transaction that is rolled back and answers with what would have happened, plus "dryRun": true. Use it to preview a change, or to validate one.

curl -X PATCH 'https://flag.nightroll.app/api/v1/orgs/acme/projects/default/flags/new-checkout?dryRun=true' \
  -H "Authorization: Bearer $FLAG_TOKEN" -H 'content-type: application/json' \
  -d '{"environmentKey": "production", "instructions": [{"kind": "turnFlagOn"}]}'
# {"outcome": "applied", "dryRun": true, "diff": {"production": [{"path": "/on", "from": false, "to": true}]}, "flag": {...}}

Organizations, projects and environments

Paths take the org’s id or slug, and project, environment and flag keys.

Flags

Semantic patch

A change is a list of instructions applied in order, all or nothing:

{
  "environmentKey": "production",
  "instructions": [
    {"kind": "turnFlagOn"},
    {"kind": "addRule", "description": "Acme staff",
     "clauses": [{"contextKind": "user", "attribute": "email", "op": "endsWith", "values": ["@acme.com"]}],
     "variation": 0},
    {"kind": "updateFallthroughVariationOrRollout",
     "rollout": {"variations": [{"variation": 0, "weight": 10000}, {"variation": 1, "weight": 90000}]}}
  ],
  "comment": "Acme first, then 10%"
}

The answer has an outcome: applied, unchanged, or changeRequest when the environment requires approval (or an agent writes to a critical environment); then changeRequest holds the request. It also has the updated flag and the diff per scope ("flag" for flag-wide settings, the environment’s key for targeting). Owners and admins may add ?bypassApprovals=true to apply directly where approval is required; it is audited.

Targeting instructions (need environmentKey):

Flag-wide instructions (no environmentKey; in an environment that requires approval, send them separately):

Clauses: {"contextKind": "user", "attribute": "email", "op": "endsWith", "values": ["@acme.com"], "negate": false}. Operators: in, startsWith, endsWith, contains, matches (regular expression), lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual (numbers), before, after (RFC 3339 or Unix milliseconds), semVerEqual, semVerLessThan, semVerGreaterThan, and segmentMatch (values are segment keys; no attribute). A rule matches when all its clauses do. Exact semantics: evaluation spec.

Rollouts: {"variations": [{"variation": 0, "weight": 25000}, {"variation": 1, "weight": 75000}], "bucketBy": "key", "contextKind": "user"}. Weights are thousandths of a percent and add up to 100000. A context always lands in the same bucket for the same flag.

Segments

GET|POST .../projects/{proj}/environments/{env}/segments, GET|PATCH|DELETE .../segments/{seg}. Create with {"key", "name"?, "included"?, "excluded"?, "includedContexts"?, "excludedContexts"?, "rules"?}; change with {"instructions", "comment"?}:

Segments in environments that require approval change through change requests too. A segment in use can’t be deleted.

Change requests

GET .../projects/{proj}/change-requests?status=&env=, POST to propose ({"kind": "flag"|"segment", "targetKey", "environmentKey", "instructions", "comment"?, "runAt"?}), GET .../change-requests/{id} (with a preview of what it would change now), and POST .../{id}/review ({"decision": "approve"|"decline"|"comment", "comment"?}), .../{id}/apply, .../{id}/cancel. A request applies once it has the environment’s minApprovals approvals (at runAt if it has one). People can’t approve their own requests unless the environment allows it; agents and tokens can propose but never review.

Schedules and cleanup

Organization

Members, invites, API keys, SSO, the audit log and usage are the platform’s, under Settings and its JSON API at /api/orgs/{org}/...; your agent reaches them with the MCP tools listed on AI & MCP.

This page as Markdown: /docs/api.md · All docs for agents: /llms.txt