Flags
A flag has a definition, shared by every environment, and a configuration in each environment: whether it's on, who it targets and what it serves.
The configuration object
{
"flagKey": "new-checkout",
"environmentKey": "production",
"version": 413,
"enabled": true,
"offVariation": 0,
"fallthroughRollout": {
"variations": [
{
"variationIndex": 1,
"weight": 20000
},
{
"variationIndex": 0,
"weight": 80000
}
]
},
"targets": [
{
"contextKind": "user",
"variation": 1,
"keys": [
"u-ana",
"qa-bot"
]
}
],
"rules": [
{
"description": "paid plans",
"clauses": [
{
"contextKind": "user",
"attribute": "plan",
"op": "in",
"values": [
"pro",
"team"
],
"negate": false
}
],
"variation": 1
}
],
"prerequisites": []
}
| Field | Notes |
|---|---|
enabled | false serves offVariation to everyone. New flags start off in every environment. |
offVariation | Index served while off. null serves the caller's default. |
fallthroughVariation / fallthroughRollout | What everyone matched by no target and no rule gets: one variation, or a split by weight. |
targets | Context keys that get a variation before any rule runs. |
rules | Checked in order, first match wins. Clauses in a rule are ANDed. See targeting rules. |
prerequisites | Other flags that must be on and serving a given variation first, as { flagKey, variation }. |
Reads speak variationIndex inside rollouts. Writes take variation.
List flags
GET/v1/admin/projects/{project}/flags
Auth: Personal access token or dashboard session, role reader or higher.
Every flag in the project, sorted by key. Add environment to get each flag's state there too, in one request.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
environment | string | Include each flag's state in this environment. | |
archived | boolean | false | With environment: include archived flags. |
Responses
{
"flags": [
{
"key": "new-checkout",
"name": "New checkout flow",
"kind": "boolean",
"archived": false
},
{
"key": "promo-banner",
"name": "Promo banner",
"kind": "string",
"archived": false
}
]
}
{
"environment": "production",
"flags": [
{
"key": "new-checkout",
"name": "New checkout flow",
"description": null,
"kind": "boolean",
"tags": [
"checkout"
],
"temporary": true,
"clientAvailable": true,
"archived": false,
"createdAt": "2026-11-17T10:00:00.000Z",
"environment": {
"enabled": true,
"version": 413,
"updatedAt": "2026-11-18T09:12:44.318Z",
"offVariation": 0,
"fallthroughVariation": null,
"fallthroughRollout": [
{
"variation": 1,
"weight": 20000
},
{
"variation": 0,
"weight": 80000
}
],
"ruleCount": 1,
"targetCount": 1,
"prerequisiteCount": 0
},
"variations": [
{
"idx": 0,
"name": "off",
"value": false
},
{
"idx": 1,
"name": "on",
"value": true
}
]
}
]
}
{
"error": "NOT_FOUND",
"message": "no such project"
}
{
"error": "NOT_FOUND",
"message": "no such environment"
}
Common errors (401, 429, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INTERNAL_ERROR"
}
Example
curl "http://127.0.0.1:3000/v1/admin/projects/acme/flags?environment=production" -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Create a flag
POST/v1/admin/projects/{project}/flags
Auth: Personal access token or dashboard session, role writer or higher.
Creates the flag in every environment of the project, off. While off it serves variation 0; turned on with nothing else set, it serves the last variation.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
key | string | yes | [A-Za-z0-9._-], up to 255. Can't be changed later. |
name | string | yes | Up to 255. |
kind | string | yes | boolean, string, number or json. Every variation is checked against it before it's served. |
variations | object[] | yes | 2 to 100 of { name?, value }. |
description | string | no | Up to 2,000. |
temporary | boolean | no | Default true. A release flag you mean to delete later, as opposed to a permanent one. |
clientAvailable | boolean | no | Default false. Only flags with true reach the client tier. The others don't even appear there. |
tags | string[] | no | Up to 32. |
Responses
{
"id": "0f3c2b1a-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
"key": "new-checkout"
}
{
"error": "INVALID_BODY",
"message": "key: Invalid input: expected string, received undefined; name: Invalid input: expected string, received undefined; kind: Invalid option: expected one of \"boolean\"|\"string\"|\"number\"|\"json\"; variations: Invalid input: expected array, received undefined"
}
{
"error": "INVALID_BODY",
"message": "key: flag keys are [A-Za-z0-9._-]"
}
{
"error": "INVALID_BODY",
"message": "variations: Too small: expected array to have >=2 items"
}
{
"error": "TOKEN_SCOPED",
"message": "an environment-scoped token cannot create flags, which affects every environment"
}
{
"error": "NOT_FOUND",
"message": "no such project"
}
{
"error": "ALREADY_EXISTS",
"message": "a flag with that key exists"
}
Common errors (401, 403, 400, 409, 422, 429, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 524288 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/flags \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"key": "new-checkout",
"name": "New checkout flow",
"kind": "boolean",
"clientAvailable": true,
"variations": [{ "name": "off", "value": false }, { "name": "on", "value": true }]
}'
Get a flag's definition
GET/v1/admin/projects/{project}/flags/{flag}
Auth: Personal access token or dashboard session, role reader or higher.
The parts shared by every environment: name, kind, tags and the variation values.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
flag | string | Flag key. |
Responses
{
"key": "new-checkout",
"name": "New checkout flow",
"description": null,
"kind": "boolean",
"tags": [
"checkout"
],
"temporary": true,
"clientAvailable": true,
"archived": false,
"createdAt": "2026-11-17T10:00:00.000Z",
"variations": [
{
"idx": 0,
"name": "off",
"value": false
},
{
"idx": 1,
"name": "on",
"value": true
}
]
}
{
"error": "NOT_FOUND",
"message": "no such flag"
}
Common errors (401, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/admin/projects/acme/flags/new-checkout -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Archive a flag
DELETE/v1/admin/projects/{project}/flags/{flag}
Auth: Personal access token or dashboard session, role writer or higher.
Removes the flag from every environment's next snapshot. SDKs then serve the caller's default with FLAG_NOT_FOUND. The flag and its history stay, and it can be restored.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
flag | string | Flag key. |
Responses
{
"archived": true
}
{
"error": "TOKEN_SCOPED",
"message": "an environment-scoped token cannot archive flags, which affects every environment"
}
{
"error": "NOT_FOUND",
"message": "no such flag"
}
Common errors (401, 403, 400, 409, 422, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X DELETE http://127.0.0.1:3000/v1/admin/projects/acme/flags/new-checkout -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Restore an archived flag
POST/v1/admin/projects/{project}/flags/{flag}/restore
Auth: Personal access token or dashboard session, role writer or higher.
Puts the flag back in every environment, with the configuration it had.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
flag | string | Flag key. |
Responses
{
"archived": false
}
{
"error": "TOKEN_SCOPED",
"message": "an environment-scoped token cannot restore flags, which affects every environment"
}
{
"error": "NOT_FOUND",
"message": "no such flag"
}
Common errors (401, 403, 400, 409, 422, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/flags/new-checkout/restore -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Get a flag's configuration
GET/v1/admin/projects/{project}/environments/{env}/flags/{flag}
Auth: Personal access token or dashboard session, role reader or higher.
The flag's configuration in one environment, with the version to send back when you change it.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Responses
{
"flagKey": "new-checkout",
"environmentKey": "production",
"version": 413,
"enabled": true,
"offVariation": 0,
"fallthroughRollout": {
"variations": [
{
"variationIndex": 1,
"weight": 20000
},
{
"variationIndex": 0,
"weight": 80000
}
]
},
"targets": [
{
"contextKind": "user",
"variation": 1,
"keys": [
"u-ana",
"qa-bot"
]
}
],
"rules": [
{
"description": "paid plans",
"clauses": [
{
"contextKind": "user",
"attribute": "plan",
"op": "in",
"values": [
"pro",
"team"
],
"negate": false
}
],
"variation": 1
}
],
"prerequisites": []
}
{
"error": "NOT_FOUND",
"message": "no such flag in that environment"
}
Common errors (401, 429, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Change a flag's configuration
PATCH/v1/admin/projects/{project}/environments/{env}/flags/{flag}
Auth: Personal access token or dashboard session, role writer or higher.
Version-checked, applied in one transaction with its audit row, then pushed to every SDK within seconds. Fields you leave out keep their values. rules, targets and prerequisites are replaced as whole lists when you send them, so read, edit and send the list back.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
expectedVersion | number | yes | The version you read. |
enabled | boolean | no | |
offVariation | number or null | no | Variation index. |
fallthroughVariation | number | no | Variation index. |
fallthroughRollout | object | no | { variations: [{ variation, weight }], contextKind?, bucketBy?, seed? }. Weights out of 100,000, summing to 100,000. contextKind buckets by another kind, like organization. seed keeps buckets when the flag key changes. |
rules | object[] | no | Up to 200 of { description?, clauses, variation } or { description?, clauses, rollout }. A clause is { attribute, op, values, contextKind?, negate? }; see the operators. |
targets | object[] | no | Up to 50 of { variation, keys, contextKind? }, up to 10,000 keys each. |
prerequisites | object[] | no | Up to 20 of { flagKey, variation }. |
comment | string | no | Saved on the audit row. |
Responses
{
"version": 414,
"auditId": "8e2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
"config": {
"flagKey": "new-checkout",
"environmentKey": "production",
"version": 414,
"enabled": true,
"offVariation": 0,
"fallthroughRollout": {
"variations": [
{
"variationIndex": 1,
"weight": 50000
},
{
"variationIndex": 0,
"weight": 50000
}
]
},
"targets": [
{
"contextKind": "user",
"variation": 1,
"keys": [
"u-ana",
"qa-bot"
]
}
],
"rules": [
{
"description": "paid plans",
"clauses": [
{
"contextKind": "user",
"attribute": "plan",
"op": "in",
"values": [
"pro",
"team"
],
"negate": false
}
],
"variation": 1
}
],
"prerequisites": []
}
}
{
"error": "INVALID_BODY",
"message": "expectedVersion: Invalid input: expected number, received undefined"
}
{
"error": "INVALID_BODY",
"message": "rules.0: a rule serves exactly one of `variation` or `rollout` (rule_outcome_xor)"
}
{
"error": "INVALID_BODY",
"message": "rules.0.clauses.0.values: a `matches` pattern was rejected: patterns must be under 1000 characters and must not nest an unbounded quantifier inside a repeated group (e.g. `(a+)+`), which can hang the evaluator on a non-matching input"
}
{
"error": "UNKNOWN_VARIATION",
"message": "flag has no variation 2"
}
{
"error": "ROLLOUT_WEIGHTS",
"message": "rollout weights must sum to 100000 (got 90000); anything less silently serves the caller's default"
}
{
"error": "UNKNOWN_PREREQUISITE",
"message": "no flag payments-v2 with variation 1 in this project"
}
{
"error": "NOT_FOUND",
"message": "no such flag in that environment"
}
{
"error": "VERSION_CONFLICT",
"message": "flag was modified concurrently: expected version 413, found 414",
"details": {
"current": {
"flagKey": "new-checkout",
"environmentKey": "production",
"version": 414,
"enabled": true,
"offVariation": 0,
"fallthroughRollout": {
"variations": [
{
"variationIndex": 1,
"weight": 50000
},
{
"variationIndex": 0,
"weight": 50000
}
]
},
"targets": [
{
"contextKind": "user",
"variation": 1,
"keys": [
"u-ana",
"qa-bot"
]
}
],
"rules": [
{
"description": "paid plans",
"clauses": [
{
"contextKind": "user",
"attribute": "plan",
"op": "in",
"values": [
"pro",
"team"
],
"negate": false
}
],
"variation": 1
}
],
"prerequisites": []
}
}
}
Common errors (401, 403, 400, 409, 422, 429, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 524288 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X PATCH http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 413,
"fallthroughRollout": {
"variations": [{ "variation": 1, "weight": 50000 }, { "variation": 0, "weight": 50000 }]
},
"comment": "widen to 50%"
}'
Turn a flag off (kill switch)
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/off
Auth: Personal access token or dashboard session, role writer or higher.
Turns the flag off with no version check and pushes it immediately, skipping the usual debounce. Flags that list this one as a prerequisite stop serving too. Use it during an incident.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
comment | string | no | Saved on the audit row. |
Responses
{
"version": 414,
"auditId": "8e2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
"alreadyOff": false
}
{
"version": 415,
"auditId": "9f3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"alreadyOff": true
}
{
"error": "NOT_FOUND",
"message": "no such flag in that environment"
}
Common errors (401, 403, 400, 409, 422, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 4096 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout/off \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "comment": "checkout erroring, INC-2231" }'
Revert to an audited state
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/revert
Auth: Personal access token or dashboard session, role writer or higher.
Restores the configuration as it was before the change in that audit entry. It goes through the ordinary write path, so it's validated and audited (as flag.reverted) like any change.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
auditId | string | yes | An audit entry id for this flag, from the audit log. |
comment | string | no |
Responses
{
"version": 415,
"auditId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"config": {
"flagKey": "new-checkout",
"environmentKey": "production",
"version": 415,
"enabled": true,
"offVariation": 0,
"fallthroughRollout": {
"variations": [
{
"variationIndex": 1,
"weight": 20000
},
{
"variationIndex": 0,
"weight": 80000
}
]
},
"targets": [
{
"contextKind": "user",
"variation": 1,
"keys": [
"u-ana",
"qa-bot"
]
}
],
"rules": [
{
"description": "paid plans",
"clauses": [
{
"contextKind": "user",
"attribute": "plan",
"op": "in",
"values": [
"pro",
"team"
],
"negate": false
}
],
"variation": 1
}
],
"prerequisites": []
}
}
{
"error": "INVALID_BODY",
"message": "auditId: Invalid UUID"
}
{
"error": "AUDIT_MISMATCH",
"message": "that audit entry is for a different flag"
}
{
"error": "NOT_FOUND",
"message": "no such audit entry"
}
Common errors (401, 403, 400, 409, 422, 429, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 4096 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout/revert \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "auditId": "8e2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c" }'
Dry-run a change
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/dry-run
Auth: Personal access token or dashboard session, role reader or higher.
Evaluates real contexts you send against the current configuration and the proposed one, and reports who would change. Nothing is saved. reassigned counts contexts that move between variations rather than in or out, which is how an accidental re-bucketing shows up; when it's high but the split barely moves, a warning says so.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
patch | object | yes | The change: the same fields as PATCH a flag's configuration, without expectedVersion. |
contexts | object[] | yes | 1 to 10,000 real contexts, like { "key": "u-ana", "plan": "pro" }. |
maxExamples | number | no | 0 to 100 individual changes to list. The rest are counted. |
Responses
{
"flagKey": "new-checkout",
"sampled": 2000,
"changed": 612,
"reassigned": 0,
"distributionBefore": {
"true": 401,
"false": 1599
},
"distributionAfter": {
"true": 1013,
"false": 987
},
"examples": [
{
"contextKey": "u-ben",
"before": false,
"after": true
}
]
}
{
"flagKey": "new-checkout",
"sampled": 2000,
"changed": 1588,
"reassigned": 1588,
"distributionBefore": {
"true": 401,
"false": 1599
},
"distributionAfter": {
"true": 399,
"false": 1601
},
"examples": [
{
"contextKey": "u-ana",
"before": true,
"after": false
}
],
"warning": "79% of sampled contexts move between variations, but the overall split changes by only 0%. That is the signature of a re-bucketing rather than a resize: the same proportion of users, a different set of them. Check whether the bucketing salt, the rollout seed, or the flag key changed."
}
{
"error": "INVALID_BODY",
"message": "contexts: Too small: expected array to have >=1 items"
}
{
"error": "NOT_FOUND",
"message": "no such flag in that environment"
}
Common errors (401, 403, 400, 409, 422, 429, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 524288 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout/dry-run \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"patch": { "fallthroughRollout": { "variations": [{ "variation": 1, "weight": 50000 }, { "variation": 0, "weight": 50000 }] } },
"contexts": [{ "key": "u-ana" }, { "key": "u-ben", "plan": "pro" }],
"maxExamples": 10
}'
Read evaluation metrics
GET/v1/admin/projects/{project}/environments/{env}/flags/{flag}/metrics
Auth: Personal access token or dashboard session, role reader or higher.
How often SDKs evaluated the flag, by variation and reason, in time buckets. The answer to "is anything still reading this flag before I delete it?"
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
hours | number | 24 | 1 to 720. |
Responses
{
"flagKey": "new-checkout",
"points": [
{
"bucketAt": "2026-11-18T09:00:00.000Z",
"variationIdx": 1,
"reason": "FALLTHROUGH",
"count": 18211
},
{
"bucketAt": "2026-11-18T09:00:00.000Z",
"variationIdx": 0,
"reason": "FALLTHROUGH",
"count": 72930
}
]
}
{
"error": "NOT_FOUND",
"message": "no such flag in that environment"
}
Common errors (401, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl "http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout/metrics?hours=72" -H "Authorization: Bearer $FEATUREKIT_TOKEN"
List recently changed flags
GET/v1/admin/projects/{project}/environments/{env}/recent
Auth: Personal access token or dashboard session, role reader or higher.
The flags changed most recently in an environment, newest first.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
Responses
{
"flags": [
{
"key": "new-checkout",
"name": "New checkout flow",
"enabled": true,
"updatedAt": "2026-11-18T09:12:44.318Z"
}
]
}
{
"error": "NOT_FOUND",
"message": "no such environment"
}
Common errors (401, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/recent -H "Authorization: Bearer $FEATUREKIT_TOKEN"