Server tier
What FeaturekitSDK calls. A server key gets the whole compiled ruleset for its environment and evaluates every flag in memory. You only need these to write a server SDK of your own.
Get the snapshot
GET/v1/snapshot/{envKey}
Auth: Server key (fk_srv_…) for this environment.
The compiled ruleset. The SDK polls it when it isn't streaming, and the ETag is the snapshot version, so a poll that's already current costs a 304 and no body.
Headers
| Header | Type | Description |
|---|---|---|
If-None-Match | string | The ETag from the last response, like "413". |
Path parameters
| Name | Type | Description |
|---|---|---|
envKey | string | Environment key, or - for whichever environment the key belongs to. |
Responses
{
"version": 413,
"environmentKey": "production",
"salt": "7f3a9c2e",
"flags": {
"new-checkout": {
"key": "new-checkout",
"version": 413,
"kind": "boolean",
"on": true,
"variations": [
false,
true
],
"offVariation": 0,
"fallthrough": {
"rollout": {
"variations": [
{
"variationIndex": 1,
"weight": 20000
},
{
"variationIndex": 0,
"weight": 80000
}
]
}
},
"prerequisites": [],
"targets": [
{
"contextKind": "user",
"variation": 1,
"keys": [
"u-ana",
"qa-bot"
]
}
],
"rules": [
{
"id": "r0",
"clauses": [
{
"contextKind": "user",
"attribute": "plan",
"op": "in",
"values": [
"pro",
"team"
],
"negate": false
}
],
"variation": 1
}
]
}
},
"segments": {}
}
No body.
Common errors (401, 403, 429, 500)
{
"error": "MISSING_SDK_KEY",
"message": "an SDK key is required"
}
{
"error": "WRONG_TIER",
"message": "SDK key rejected"
}
{
"error": "ENVIRONMENT_MISMATCH",
"message": "this key is not for that environment"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/snapshot/production \
-H "Authorization: Bearer $FEATUREKIT_SDK_KEY" \
-H 'If-None-Match: "412"'
Stream changes
GET/v1/stream/{envKey}
Auth: Server key (fk_srv_…) for this environment.
Server-sent events. Each event's id is the snapshot version. Reconnect with Last-Event-ID and you get only the patches since, or a full put if they've been trimmed (the last 200 are kept). A heartbeat comment arrives every 30 seconds.
Headers
| Header | Type | Description |
|---|---|---|
Last-Event-ID | number | The version you hold. |
Path parameters
| Name | Type | Description |
|---|---|---|
envKey | string | Environment key, or -. |
| Event | Data |
|---|---|
put | The whole snapshot. Replace what you hold, unless its version is older. |
patch | One compiled flag. Apply it if its version is newer than the one you hold. |
delete | { "key": "…" }: the flag was archived. |
segment-patch | Members added to and removed from one segment. |
reconnect | { "reason": "shutdown", "afterMs": 2400 }: the node is draining. Reconnect after that delay. |
Responses
id: 413
event: put
data: {"version":413,"environmentKey":"production","flags":{…},"segments":{}}
id: 414
event: patch
data: {"key":"new-checkout","version":414,"on":false,…}
{
"error": "STREAM_CAPACITY",
"message": "stream capacity reached; fall back to polling"
}
Common errors (401, 403, 429, 500)
{
"error": "MISSING_SDK_KEY",
"message": "an SDK key is required"
}
{
"error": "WRONG_TIER",
"message": "SDK key rejected"
}
{
"error": "ENVIRONMENT_MISMATCH",
"message": "this key is not for that environment"
}
{
"error": "RATE_LIMITED",
"retryAfterSeconds": 12
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -N http://127.0.0.1:3000/v1/stream/production \
-H "Authorization: Bearer $FEATUREKIT_SDK_KEY" \
-H "Last-Event-ID: 412"
Send evaluation summaries
POST/v1/events
Auth: Any SDK key: server, client or mobile.
Counts of evaluations, grouped by flag, variation and reason, which feed the metrics. Analytics may drop data, so a batch that fails to store still answers 202.
Body
| Field | Type | Required | Description |
|---|---|---|---|
summaries | object[] | yes | Up to 10,000 of { flagKey, count, variationIndex?, reason?, uniqueContexts? }. A missing variationIndex means the default was served. |
bucketAt | number | no | Epoch ms. Within the last 24 hours and not more than 5 minutes ahead. Left out, it's the arrival time. |
dropped | number | no | How many records the SDK dropped before sending. |
Responses
No body.
{
"dropped": "bucket_out_of_range"
}
{
"error": "INVALID_BATCH",
"message": "malformed evaluation summary batch"
}
Common errors (401, 429, 400, 413, 500)
{
"error": "MISSING_SDK_KEY",
"message": "an SDK key is required"
}
{
"error": "WRONG_TIER",
"message": "SDK key rejected"
}
{
"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/events \
-H "Authorization: Bearer $FEATUREKIT_SDK_KEY" \
-H "Content-Type: application/json" \
-d '{ "summaries": [{ "flagKey": "new-checkout", "variationIndex": 1, "reason": "FALLTHROUGH", "count": 500 }] }'