Client tier
Send one context, get its evaluated values, then stream changes to them. No rules, segments or rollout percentages ever leave the server. The client SDK is a wrapper over exactly these two calls.
Evaluate a context
POST/v1/client/state
Auth: Client (fk_clt_…) or mobile (fk_mob_…) key, in the header or a key query parameter.
Evaluates every flag with clientAvailable: true for one context. Flags without it are absent, not filtered, so unreleased work isn't even named. connectionId opens the stream; an empty one means this node is at capacity, so poll this endpoint instead.
Body
| Field | Type | Required | Description |
|---|---|---|---|
context | object | yes | { key, …attributes }, or a multi-context. Limits: 5 kinds, 60 attributes, 512-character keys, 1,024-character strings, 100-item arrays, 5 levels deep. |
seq | number | no | Any increasing number of yours, echoed back so you can drop a response that arrives after a newer one. |
signature | string | in production | HMAC of the context. See secure mode. |
expiresAt | number | with signature | Epoch seconds. At most 24 hours out by default. |
Responses
{
"contextHash": "3f9a0c1d7e2b4a6f9c8d1e0f2a3b4c5d",
"seq": 1,
"version": 413,
"values": {
"new-checkout": {
"value": false,
"variationIndex": 0,
"reason": "FALLTHROUGH"
},
"loyalty-discount": {
"value": 0,
"variationIndex": 0,
"reason": "FALLTHROUGH"
},
"promo-banner": {
"value": "Upgrade to Pro and save 10%.",
"variationIndex": 1,
"reason": "RULE_MATCH"
}
},
"connectionId": "c_8Xk2pQ9vR4mL7nW1"
}
{
"error": "MISSING_CONTEXT",
"message": "a context is required"
}
{
"error": "CONTEXT_TOO_MANY_ATTRIBUTES",
"message": "context rejected"
}
{
"error": "SIGNATURE_MISSING",
"message": "context signature rejected"
}
{
"error": "SIGNATURE_INVALID",
"message": "context signature rejected"
}
{
"error": "SIGNATURE_EXPIRED",
"message": "context signature rejected"
}
{
"error": "SIGNATURE_TTL_TOO_LONG",
"message": "context signature rejected"
}
{
"error": "SECURE_MODE_UNCONFIGURED",
"message": "secure mode required but no secret"
}
Common errors (401, 429, 400, 413, 500)
{
"error": "MISSING_SDK_KEY",
"message": "a client key is required"
}
{
"error": "WRONG_TIER",
"message": "client key rejected"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 65536 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/client/state \
-H "Authorization: Bearer $FEATUREKIT_CLIENT_KEY" \
-H "Content-Type: application/json" \
-d '{ "context": { "key": "u-ana", "plan": "free" }, "seq": 1 }'
import { FeaturekitClient } from "featurekit-client";
const flags = new FeaturekitClient({ clientKey, baseUrl, context: { key: "u-ana", plan: "free" } });
await flags.ready();
flags.get("new-checkout", false);
Stream value changes
GET/v1/client/stream
Auth: Client (fk_clt_…) or mobile (fk_mob_…) key, in the header or a key query parameter.
Server-sent events for the context the state call registered. values is a delta with only the flags whose value changed for this context: merge it, don't replace. When the stream ends for any reason, call state again and reopen.
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
connection | string | connectionId from the state call. | |
key | string | The client key, for EventSource, which can't set headers. |
Responses
event: ready
data: {"version":413}
event: values
data: {"version":414,"values":{"new-checkout":{"value":true,"variationIndex":1,"reason":"RULE_MATCH"}}}
{
"error": "SIGNATURE_EXPIRED",
"message": "context signature expired; identify again"
}
{
"error": "UNKNOWN_CONNECTION",
"message": "call POST /v1/client/state first"
}
Common errors (401, 429, 500)
{
"error": "MISSING_SDK_KEY",
"message": "a client key is required"
}
{
"error": "WRONG_TIER",
"message": "client key rejected"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -N "http://127.0.0.1:3000/v1/client/stream?connection=c_8Xk2pQ9vR4mL7nW1" \
-H "Authorization: Bearer $FEATUREKIT_CLIENT_KEY"
flags.on("change", (keys) => render()); // the SDK opens the stream for you