Configuration and evaluation

Frozen legacy delivery

GET /api/v1/config requires an environment sdk_ key and returns the full legacy document. GET /api/v1/public-config requires a pub_ key and returns only legacy flags with clientEnabled: true; legacy rules and overrides are always empty on the client route.

curl https://superflag.sh/api/v1/public-config \
  -H "Authorization: Bearer pub_..."

{
  "appId": "app-id",
  "env": "prod",
  "version": 42,
  "doc": {
    "flags": {
      "checkout": {
        "type": "bool",
        "value": true,
        "clientEnabled": true
      }
    },
    "overrides": {},
    "rules": {}
  },
  "ttlSeconds": 60
}

This envelope is a frozen compatibility surface. New server integrations should prefer the Node SDK and advanced schema.

Advanced configuration

GET /api/v1/advanced-config returns composed core schema v1. Environment credentials infer app/environment from the key. CLI and app-admin reads supply ?appId=<id>&env=<slug>.

{
  "schemaVersion": 1,
  "config": {
    "schemaVersion": 1,
    "source": { "app": "store", "environment": "prod" },
    "configVersion": 42,
    "flags": {}
  },
  "privacy": {
    "allowedContextAttributes": ["plan", "country"]
  },
  "delivery": "server",
  "ttlSeconds": 60,
  "migration": {
    "legacyComposed": true,
    "storedAdvancedConfig": true
  }
}

Advanced definitions win key collisions; migrated legacy-only flags fill missing keys. An sdk_ key receives server delivery. A pub_ key receives only explicit client-visible flags and dependencies, with arbitrary metadata removed by default.

ETag revalidation and quota

Send the last opaque ETag in If-None-Match. A matching credential, representation, source, and version returns 304 with no body and renews the SDK freshness window. Both 200 and 304 environment config responses count as one monthly sync. Free includes 25,000 syncs per month per environment; Pro includes 1,000,000. 304 contributes zero response bytes. Management reads with cli_ or admin_ credentials do not count as environment config syncs. Quota exhaustion returns 429 with code MONTHLY_CONFIG_SYNC_QUOTA_EXCEEDED. Metering unavailability fails closed with retryable 503 CONFIG_SYNC_METERING_UNAVAILABLE.

Remote server evaluation

POST /api/v1/evaluate requires an environment sdk_ key. Use it when targeting rules must remain in Superflag rather than being synchronized to the application server.

curl https://superflag.sh/api/v1/evaluate \
  -H "Authorization: Bearer sdk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "flagKey": "checkout",
    "context": {
      "targetingKey": "user-123",
      "attributes": { "plan": "pro", "country": "US" }
    },
    "defaultValue": false
  }'

The response contains schema version, typed evaluation details, and the list of accepted context attributes. Unknown or unapproved attributes are removed. Evaluation failures return the typed fallback inside details; invalid request shape is a validation error. Remote evaluation adds a network round trip. Bound caller timeout/retry and do not place it on a render-critical hot path without an application-specific latency and caching strategy.

Start here

Node and server SDK

React SDK

React Native and Expo

Core SDK

CLI and agents

Feature decisions

HTTP API

Configuration and evaluation

Configuration and evaluation

Frozen legacy delivery

Advanced configuration

ETag revalidation and quota

Remote server evaluation

​Configuration and evaluation

​Frozen legacy delivery

​Advanced configuration

​ETag revalidation and quota

​Remote server evaluation

Configuration and evaluation

Frozen legacy delivery

Advanced configuration

ETag revalidation and quota

Remote server evaluation