Star
API reference

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

HeaderTypeDescription
If-None-MatchstringThe ETag from the last response, like "413".

Path parameters

NameTypeDescription
envKeystringEnvironment 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

HeaderTypeDescription
Last-Event-IDnumberThe version you hold.

Path parameters

NameTypeDescription
envKeystringEnvironment key, or -.
EventData
putThe whole snapshot. Replace what you hold, unless its version is older.
patchOne compiled flag. Apply it if its version is newer than the one you hold.
delete{ "key": "…" }: the flag was archived.
segment-patchMembers 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

FieldTypeRequiredDescription
summariesobject[]yesUp to 10,000 of { flagKey, count, variationIndex?, reason?, uniqueContexts? }. A missing variationIndex means the default was served.
bucketAtnumbernoEpoch ms. Within the last 24 hours and not more than 5 minutes ahead. Left out, it's the arrival time.
droppednumbernoHow 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 }] }'