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
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment 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
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
key | string | yes | [A-Za-z0-9._-]. |
name | string | yes | |
description | string | no | |
external | boolean | no | Default 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
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
segment | string | Segment 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
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
segment | string | Segment key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
add | object[] | no | { contextKey, contextKind?, excluded? }. contextKind defaults to user. |
remove | object[] | 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
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
segment | string | Segment 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"