Star
API reference

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

FieldTypeRequiredDescription
contextobjectyes{ key, …attributes }, or a multi-context. Limits: 5 kinds, 60 attributes, 512-character keys, 1,024-character strings, 100-item arrays, 5 levels deep.
seqnumbernoAny increasing number of yours, echoed back so you can drop a response that arrives after a newer one.
signaturestringin productionHMAC of the context. See secure mode.
expiresAtnumberwith signatureEpoch 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

NameTypeDefaultDescription
connectionstringconnectionId from the state call.
keystringThe 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