Star
API reference

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": []
}
FieldNotes
enabledfalse serves offVariation to everyone. New flags start off in every environment.
offVariationIndex served while off. null serves the caller's default.
fallthroughVariation / fallthroughRolloutWhat everyone matched by no target and no rule gets: one variation, or a split by weight.
targetsContext keys that get a variation before any rule runs.
rulesChecked in order, first match wins. Clauses in a rule are ANDed. See targeting rules.
prerequisitesOther 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

NameTypeDescription
projectstringProject key.

Query parameters

NameTypeDefaultDescription
environmentstringInclude each flag's state in this environment.
archivedbooleanfalseWith 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

NameTypeDescription
projectstringProject key.

Body

FieldTypeRequiredDescription
keystringyes[A-Za-z0-9._-], up to 255. Can't be changed later.
namestringyesUp to 255.
kindstringyesboolean, string, number or json. Every variation is checked against it before it's served.
variationsobject[]yes2 to 100 of { name?, value }.
descriptionstringnoUp to 2,000.
temporarybooleannoDefault true. A release flag you mean to delete later, as opposed to a permanent one.
clientAvailablebooleannoDefault false. Only flags with true reach the client tier. The others don't even appear there.
tagsstring[]noUp 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

NameTypeDescription
projectstringProject key.
flagstringFlag 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

NameTypeDescription
projectstringProject key.
flagstringFlag 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

NameTypeDescription
projectstringProject key.
flagstringFlag 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.

Body

FieldTypeRequiredDescription
expectedVersionnumberyesThe version you read.
enabledbooleanno
offVariationnumber or nullnoVariation index.
fallthroughVariationnumbernoVariation index.
fallthroughRolloutobjectno{ 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.
rulesobject[]noUp to 200 of { description?, clauses, variation } or { description?, clauses, rollout }. A clause is { attribute, op, values, contextKind?, negate? }; see the operators.
targetsobject[]noUp to 50 of { variation, keys, contextKind? }, up to 10,000 keys each.
prerequisitesobject[]noUp to 20 of { flagKey, variation }.
commentstringnoSaved 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.

Body

FieldTypeRequiredDescription
commentstringnoSaved 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.

Body

FieldTypeRequiredDescription
auditIdstringyesAn audit entry id for this flag, from the audit log.
commentstringno

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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.

Body

FieldTypeRequiredDescription
patchobjectyesThe change: the same fields as PATCH a flag's configuration, without expectedVersion.
contextsobject[]yes1 to 10,000 real contexts, like { "key": "u-ana", "plan": "pro" }.
maxExamplesnumberno0 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.

Query parameters

NameTypeDefaultDescription
hoursnumber241 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

NameTypeDescription
projectstringProject key.
envstringEnvironment 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"