Star
API reference

Segments

A segment is a named list of context keys a rule can target with segmentMatch. Large ones are compressed into the snapshot, so a check never makes a network call.

List segments

GET/v1/admin/projects/{project}/environments/{env}/segments

Auth: Personal access token or dashboard session, role reader or higher.

Path parameters

NameTypeDescription
projectstringProject key.
envstringEnvironment key.

Responses

{
  "segments": [
    {
      "key": "beta-testers",
      "name": "Beta testers",
      "external": false,
      "memberCount": 1240
    },
    {
      "key": "enterprise",
      "name": "Enterprise accounts",
      "external": true,
      "memberCount": 512000
    }
  ]
}
{
  "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/segments -H "Authorization: Bearer $FEATUREKIT_TOKEN"

Create a segment

POST/v1/admin/projects/{project}/environments/{env}/segments

Auth: Personal access token or dashboard session, role writer or higher.

Path parameters

NameTypeDescription
projectstringProject key.
envstringEnvironment key.

Body

FieldTypeRequiredDescription
keystringyes[A-Za-z0-9._-].
namestringyes
descriptionstringno
externalbooleannoDefault false. Marks a list synced from another system, so people know not to edit it by hand.

Responses

{
  "id": "e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091",
  "key": "beta-testers"
}
{
  "error": "INVALID_BODY",
  "message": "key: Invalid input: expected string, received undefined; name: Invalid input: expected string, received undefined"
}
{
  "error": "ALREADY_EXISTS",
  "message": "a segment with that key exists"
}
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 524288 bytes"
}
{
  "error": "INTERNAL_ERROR"
}

Example

curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/segments \
  -H "Authorization: Bearer $FEATUREKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key": "beta-testers", "name": "Beta testers" }'

Get a segment

GET/v1/admin/projects/{project}/environments/{env}/segments/{segment}

Auth: Personal access token or dashboard session, role reader or higher.

Path parameters

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
segmentstringSegment key.

Responses

{
  "id": "e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091",
  "key": "beta-testers",
  "name": "Beta testers",
  "description": null,
  "external": false,
  "memberCount": 1240,
  "version": 7,
  "ruleCount": 0,
  "updatedAt": "2026-11-18T09:12:44.318Z"
}
{
  "error": "NOT_FOUND",
  "message": "no such segment"
}
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/segments/beta-testers -H "Authorization: Bearer $FEATUREKIT_TOKEN"

Add or remove members

POST/v1/admin/projects/{project}/environments/{env}/segments/{segment}/members

Auth: Personal access token or dashboard session, role writer or higher.

One page of an import: up to 50,000 additions and 50,000 removals per request. A 10-million-member list is 200 requests, each one its own transaction you can retry on its own. An excluded member is left out even if a segment rule would include it.

Path parameters

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
segmentstringSegment key.

Body

FieldTypeRequiredDescription
addobject[]no{ contextKey, contextKind?, excluded? }. contextKind defaults to user.
removeobject[]no{ contextKey, contextKind? }.

Responses

{
  "version": 8,
  "memberCount": 1243
}
{
  "error": "NOT_FOUND",
  "message": "no such segment"
}
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 5242880 bytes"
}
{
  "error": "INTERNAL_ERROR"
}

Example

curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/segments/beta-testers/members \
  -H "Authorization: Bearer $FEATUREKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "add": [{ "contextKey": "u-ana" }, { "contextKey": "u-ben" }, { "contextKey": "org_9", "contextKind": "organization" }],
    "remove": [{ "contextKey": "u-cy" }]
  }'

Delete a segment

DELETE/v1/admin/projects/{project}/environments/{env}/segments/{segment}

Auth: Personal access token or dashboard session, role writer or higher.

Refused while any rule still names the segment: deleting it would silently change who those rules target.

Path parameters

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
segmentstringSegment key.

Responses

{
  "deleted": true
}
{
  "error": "NOT_FOUND",
  "message": "no such segment"
}
{
  "error": "SEGMENT_IN_USE",
  "message": "still referenced by: new-checkout, promo-banner"
}
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/environments/production/segments/beta-testers -H "Authorization: Bearer $FEATUREKIT_TOKEN"