Star
API reference

API reference

Every featurekit endpoint, request and response. The dashboard, the MCP server and both SDKs call this API, so anything here works from any language.

Base URL

The API is served by FeaturekitServer, on port 3000 by default. Three groups of routes live under /v1, plus the probes (/live, /ready, /health, /metrics).

PrefixWho calls itCredential
/v1/admin/…The dashboard, scripts, CI, the MCP serverPersonal access token or session
/v1/snapshot, /v1/stream, /v1/eventsThe server SDKServer key
/v1/client/…Browsers, mobile apps, any HTTP clientClient or mobile key
curl http://127.0.0.1:3000/v1/admin/projects -H "Authorization: Bearer $FEATUREKIT_TOKEN"

Authentication

Admin routes take a personal access token as Authorization: Bearer fk_pat_…. Create one in the dashboard under Settings, or with POST /v1/admin/tokens. A token acts as the member who made it, can be limited to some environments, and can expire.

The dashboard uses a session cookie instead. A write made with the cookie must also send x-featurekit-csrf: 1, which a cross-site form can't do. When both are present, the token wins.

The SDK routes take an SDK key, made per environment with POST …/keys:

KeyLooks likeGets
Serverfk_srv_…The compiled ruleset for its environment. Rejected by the client routes. Keep it secret.
Clientfk_clt_…Evaluated values for one context, never the rules. Rejected by the server routes. Safe to ship in a page.
Mobilefk_mob_…The same as a client key, under its own type so mobile traffic can be revoked on its own.

Tokens and keys are stored hashed. The plaintext is in the response that creates them and nowhere else.

Roles

Each member has one role, and each role includes the ones before it.

RoleCan
readerRead everything except keys and members. Dry-run a change. Raise a change request.
writerChange flags and segments, schedule changes, approve requests, create tokens.
adminCreate projects and environments, manage SDK keys, verify the audit chain.
ownerManage members.

A token limited to some environments can't act outside them, and can't create projects, environments or flags (which reach every environment). Something in another environment answers 404, the same as something that doesn't exist.

Addressing

Everything is addressed by key, never by id: /projects/acme/environments/production/flags/new-checkout. Keys are [A-Za-z0-9._-], up to 255 characters. Another tenant's flag and a missing flag both answer 404, so keys can't be probed.

Variations are referenced by index into the flag's variations array. Rollout weights are integers out of 100,000, so 20% is 20000, and a rollout's weights must add up to exactly 100,000.

Requests and responses

Bodies are JSON. Most admin writes take up to 512 KB, a segment import page up to 5 MB. Every response carries an x-request-id header, the same id the server logs. Send your own x-request-id or traceparent to have it carried through.

Errors have an error code and a message. A few add details, like the current configuration on a version conflict:

{
  "error": "NOT_FOUND",
  "message": "no such flag in that environment"
}

A body that fails validation answers 400 INVALID_BODY, with every failing field in the message as path: problem, joined by ; :

{
  "error": "INVALID_BODY",
  "message": "key: flag keys are [A-Za-z0-9._-]"
}

An unknown path answers 404 NOT_FOUND with the path. A known path with the wrong verb answers 405 METHOD_NOT_ALLOWED.

Errors every route can return

Each endpoint lists the ones that apply to it under Common errors.

{
  "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": "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"
}

Versions and conflicts

Every flag configuration has a version. A write must send the version it read as expectedVersion. If someone else saved in between, the write is refused with 409 VERSION_CONFLICT and the current configuration in details.current, so nobody's edit is silently overwritten. Read again, reapply your change, and retry.

The kill switch is the exception: it needs no version, so turning something off during an incident never waits on a read.

Idempotency

Send Idempotency-Key on any admin write, and a retry with the same key within 10 minutes gets the first response back instead of applying twice. The key is per caller and per route. Up to 200 characters of [A-Za-z0-9._:-]. A failed request isn't remembered, so you can fix it and retry with the same key.

Rate limits

Counted per caller, per node, per minute. Behind a load balancer over N nodes a caller can reach N times these in total. Change them with the configuration variables.

RouteDefaultVariable
POST /v1/client/state600RATE_LIMIT_CLIENT_STATE_PER_MIN
GET /v1/snapshot/{envKey}240RATE_LIMIT_SNAPSHOT_PER_MIN
Both streams (connection attempts)60RATE_LIMIT_STREAM_PER_MIN
POST /v1/events120RATE_LIMIT_EVENTS_PER_MIN
POST /v1/admin/auth/login10RATE_LIMIT_LOGIN_PER_MIN
Admin routes marked with a 429 below300RATE_LIMIT_ADMIN_PER_MIN

CORS

Only the client tier answers browsers, and only for the exact origins in CORS_ALLOWED_ORIGINS. Never *. The admin routes send no CORS headers at all: the dashboard is served from the same origin.

All endpoints

MethodPathDoes
GET/v1/admin/projects/{project}/flagsList flags
POST/v1/admin/projects/{project}/flagsCreate a flag
GET/v1/admin/projects/{project}/flags/{flag}Get a flag's definition
DELETE/v1/admin/projects/{project}/flags/{flag}Archive a flag
POST/v1/admin/projects/{project}/flags/{flag}/restoreRestore an archived flag
GET/v1/admin/projects/{project}/environments/{env}/flags/{flag}Get a flag's configuration
PATCH/v1/admin/projects/{project}/environments/{env}/flags/{flag}Change a flag's configuration
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/offTurn a flag off (kill switch)
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/revertRevert to an audited state
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/dry-runDry-run a change
GET/v1/admin/projects/{project}/environments/{env}/flags/{flag}/metricsRead evaluation metrics
GET/v1/admin/projects/{project}/environments/{env}/recentList recently changed flags
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/scheduleSchedule a change
GET/v1/admin/projects/{project}/environments/{env}/flags/{flag}/scheduleList scheduled changes
DELETE/v1/admin/projects/{project}/environments/{env}/flags/{flag}/schedule/{scheduleId}Cancel a scheduled change
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/requestsRaise a change request
GET/v1/admin/projects/{project}/environments/{env}/flags/{flag}/requestsList change requests
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/requests/{requestId}/approveApprove a change request
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/requests/{requestId}/rejectReject a change request
GET/v1/admin/projects/{project}/environments/{env}/segmentsList segments
POST/v1/admin/projects/{project}/environments/{env}/segmentsCreate a segment
GET/v1/admin/projects/{project}/environments/{env}/segments/{segment}Get a segment
POST/v1/admin/projects/{project}/environments/{env}/segments/{segment}/membersAdd or remove members
DELETE/v1/admin/projects/{project}/environments/{env}/segments/{segment}Delete a segment
GET/v1/admin/projectsList projects
POST/v1/admin/projectsCreate a project
DELETE/v1/admin/projects/{project}Delete a project
GET/v1/admin/projects/{project}/environmentsList environments
POST/v1/admin/projects/{project}/environmentsCreate an environment
GET/v1/admin/projects/{project}/environments/{env}/keysList keys
POST/v1/admin/projects/{project}/environments/{env}/keysCreate a key
DELETE/v1/admin/projects/{project}/environments/{env}/keys/{keyId}Revoke a key
GET/v1/admin/projects/{project}/auditRead the audit log
GET/v1/admin/projects/{project}/audit/verifyVerify the audit chain
GET/v1/admin/auth/bootstrapCheck for accounts
POST/v1/admin/auth/loginSign in
POST/v1/admin/auth/logoutSign out
GET/v1/admin/auth/meWho am I
POST/v1/admin/auth/passwordChange your password
GET/v1/admin/membersList members
POST/v1/admin/membersAdd a member
PATCH/v1/admin/members/{memberId}Update a member
DELETE/v1/admin/members/{memberId}Remove a member
GET/v1/admin/tokensList your tokens
POST/v1/admin/tokensCreate a token
DELETE/v1/admin/tokens/{tokenId}Revoke a token
GET/v1/snapshot/{envKey}Get the snapshot
GET/v1/stream/{envKey}Stream changes
POST/v1/eventsSend evaluation summaries
POST/v1/client/stateEvaluate a context
GET/v1/client/streamStream value changes
GET/liveLiveness
GET/readyReadiness
GET/healthHealth summary
GET/metricsPrometheus metrics