Star
API reference

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

FieldTypeRequiredDescription
keystringyes[A-Za-z0-9._-].
namestringyes

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

NameTypeDescription
projectstringProject 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

NameTypeDescription
projectstringProject 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

NameTypeDescription
projectstringProject key.

Body

FieldTypeRequiredDescription
keystringyes[A-Za-z0-9._-].
namestringyes
isProductionbooleannoDefault false. Production requires signed client contexts (secure mode), and the dashboard and the MCP server warn on changes to it.
colorstringnoFor 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 }'