Projects and environments
A project holds flags and segments. Each project has environments, like development and production, and each environment has its own configuration, keys and snapshot.
List projects
GET/v1/admin/projects
Auth: Personal access token or dashboard session, role reader or higher.
The projects the caller can see, with their environment keys. A scoped token sees only its own environments.
Responses
200 OK Found.
{
"projects": [
{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"key": "acme",
"name": "Acme",
"environments": [
"development",
"production"
]
}
]
}
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 -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Create a project
POST/v1/admin/projects
Auth: Personal access token or dashboard session, role admin or higher.
Body
| Field | Type | Required | Description |
|---|---|---|---|
key | string | yes | [A-Za-z0-9._-]. |
name | string | yes |
Responses
{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"key": "acme"
}
{
"error": "INVALID_BODY",
"message": "key: Invalid input: expected string, received undefined; name: Invalid input: expected string, received undefined"
}
{
"error": "TOKEN_SCOPED",
"message": "an environment-scoped token cannot create projects"
}
{
"error": "ALREADY_EXISTS",
"message": "a project 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 admin 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 \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "key": "acme", "name": "Acme" }'
Delete a project
DELETE/v1/admin/projects/{project}
Auth: Personal access token or dashboard session, role admin or higher.
Deletes the project, its environments, flags, segments and SDK keys. Keys stop working at once. This can't be undone.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
Responses
{
"deleted": true
}
{
"error": "TOKEN_SCOPED",
"message": "an environment-scoped token cannot delete projects"
}
{
"error": "NOT_FOUND",
"message": "no such project"
}
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 admin 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 -H "Authorization: Bearer $FEATUREKIT_TOKEN"
List environments
GET/v1/admin/projects/{project}/environments
Auth: Personal access token or dashboard session, role reader or higher.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
Responses
{
"environments": [
{
"id": "f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f809102",
"key": "development",
"name": "Development",
"color": null,
"isProduction": false,
"snapshotVersion": 88,
"createdAt": "2026-11-17T10:00:00.000Z"
},
{
"id": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"key": "production",
"name": "Production",
"color": "#FF7A85",
"isProduction": true,
"snapshotVersion": 413,
"createdAt": "2026-11-17T10:00:00.000Z"
}
]
}
{
"error": "NOT_FOUND",
"message": "no such project"
}
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 -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Create an environment
POST/v1/admin/projects/{project}/environments
Auth: Personal access token or dashboard session, role admin or higher.
Every existing flag is added to it, off.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
key | string | yes | [A-Za-z0-9._-]. |
name | string | yes | |
isProduction | boolean | no | Default false. Production requires signed client contexts (secure mode), and the dashboard and the MCP server warn on changes to it. |
color | string | no | For the dashboard's environment switcher. |
Responses
{
"id": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"key": "production"
}
{
"error": "INVALID_BODY",
"message": "name: Invalid input: expected string, received undefined"
}
{
"error": "TOKEN_SCOPED",
"message": "an environment-scoped token cannot create environments"
}
{
"error": "ALREADY_EXISTS",
"message": "an environment 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 admin 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 \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "key": "production", "name": "Production", "isProduction": true }'