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).
| Prefix | Who calls it | Credential |
|---|---|---|
/v1/admin/… | The dashboard, scripts, CI, the MCP server | Personal access token or session |
/v1/snapshot, /v1/stream, /v1/events | The server SDK | Server key |
/v1/client/… | Browsers, mobile apps, any HTTP client | Client 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:
| Key | Looks like | Gets |
|---|---|---|
| Server | fk_srv_… | The compiled ruleset for its environment. Rejected by the client routes. Keep it secret. |
| Client | fk_clt_… | Evaluated values for one context, never the rules. Rejected by the server routes. Safe to ship in a page. |
| Mobile | fk_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.
| Role | Can |
|---|---|
reader | Read everything except keys and members. Dry-run a change. Raise a change request. |
writer | Change flags and segments, schedule changes, approve requests, create tokens. |
admin | Create projects and environments, manage SDK keys, verify the audit chain. |
owner | Manage 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.
| Route | Default | Variable |
|---|---|---|
POST /v1/client/state | 600 | RATE_LIMIT_CLIENT_STATE_PER_MIN |
GET /v1/snapshot/{envKey} | 240 | RATE_LIMIT_SNAPSHOT_PER_MIN |
| Both streams (connection attempts) | 60 | RATE_LIMIT_STREAM_PER_MIN |
POST /v1/events | 120 | RATE_LIMIT_EVENTS_PER_MIN |
POST /v1/admin/auth/login | 10 | RATE_LIMIT_LOGIN_PER_MIN |
Admin routes marked with a 429 below | 300 | RATE_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.