Feature flags API

Feature flags are on/off (or multivariate) toggles you flip per environment with no deploy. All endpoints on this page require the secret management key vsk_live_….

Base URL: https://statskit.ai/api/v1

Flags

List flags

GET /flags

curl https://statskit.ai/api/v1/flags \
  -H "Authorization: Bearer vsk_live_..."

Create a flag

POST /flags

Field	Type	Notes
`key`	string	Stable key referenced from code, lowercase letters, digits, `_`, `-`, `.` only
`name`	string	Human-readable name
`description`	string	Optional
`type`	`boolean` \| `string` \| `number` \| `json`	Default `boolean`
`variations`	array	Required for non-boolean: `[{ idx, value, name }]` (2+)
`temporary`	boolean	Mark as a cleanup-later flag (default true)
`bucketBy`	string	Attribute used for bucketing (default `key`)
`tags`	string[]	Optional

The flag is created disabled in every environment. Enable it per-environment with the environment endpoints below.

curl -X POST https://statskit.ai/api/v1/flags \
  -H "Authorization: Bearer vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "key": "new_dashboard", "name": "New dashboard", "type": "boolean" }'

A multivariate flag supplies its own variations:

{
  "key": "cta_copy",
  "name": "CTA copy",
  "type": "string",
  "variations": [
    { "idx": 0, "value": "Sign up", "name": "Control" },
    { "idx": 1, "value": "Get started", "name": "B" }
  ]
}

Get a flag

GET /flags/:key

curl https://statskit.ai/api/v1/flags/new_dashboard \
  -H "Authorization: Bearer vsk_live_..."

Update flag metadata

PATCH /flags/:key

Update name, description, tags, temporary, not per-environment behavior.

curl -X PATCH https://statskit.ai/api/v1/flags/new_dashboard \
  -H "Authorization: Bearer vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "description": "Ships the redesigned dashboard", "tags": ["ui"] }'

Archive and restore

POST /flags/:key/archive POST /flags/:key/restore

curl -X POST https://statskit.ai/api/v1/flags/new_dashboard/archive \
  -H "Authorization: Bearer vsk_live_..."

Audit, code references, and metrics

GET /flags/:key/audit: change history.

GET /flags/:key/code-refs: where the flag key is referenced in code.

GET /flags/:key/metrics: flag-attached metric results.

curl https://statskit.ai/api/v1/flags/new_dashboard/audit \
  -H "Authorization: Bearer vsk_live_..."

Environments

Each flag has independent behavior per environment (e.g. production, staging).

Get a flag’s environment config

GET /flags/:key/environments/:env

curl https://statskit.ai/api/v1/flags/new_dashboard/environments/production \
  -H "Authorization: Bearer vsk_live_..."

Set a flag’s environment config

PUT /flags/:key/environments/:env

Set whether the flag is enabled, the off variation, and the fallthrough (a fixed variation, or a percentage rollout).

curl -X PUT https://statskit.ai/api/v1/flags/new_dashboard/environments/production \
  -H "Authorization: Bearer vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "offVariation": 0,
    "fallthrough": { "rollout": [ { "idx": 0, "weight": 90 }, { "idx": 1, "weight": 10 } ] }
  }'

A single-variation fallthrough:

{ "enabled": true, "offVariation": 0, "fallthrough": { "variation": 1 } }

Toggle a flag in an environment

POST /flags/:key/environments/:env/toggle

The everyday on/off (and kill switch). Republishes compiled config to the edge immediately.

curl -X POST https://statskit.ai/api/v1/flags/new_dashboard/environments/production/toggle \
  -H "Authorization: Bearer vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Targeting rules

Get rules

GET /flags/:key/environments/:env/rules

curl https://statskit.ai/api/v1/flags/new_dashboard/environments/production/rules \
  -H "Authorization: Bearer vsk_live_..."

Set rules

PUT /flags/:key/environments/:env/rules

Clause-based targeting. Each rule matches a context by attribute clauses and serves a variation (or a rollout) before the fallthrough applies.

curl -X PUT https://statskit.ai/api/v1/flags/new_dashboard/environments/production/rules \
  -H "Authorization: Bearer vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "clauses": [ { "attribute": "plan", "op": "in", "values": ["pro", "enterprise"] } ],
        "variation": 1
      }
    ]
  }'