Evaluate over HTTP

POST /v1/evaluate evaluates one or more keys in the project environment bound to the presented key. Use it when a local released SDK is unavailable or current hosted configuration is required.

Server callers authenticate with a secret runtime key carrying runtime:evaluate. Browser callers use a different publishable key and additional origin and exposure checks.

Send a batch

curl https://api.featuregate.dev/v1/evaluate \
-H "Authorization: Bearer $FEATUREGATE_RUNTIME_KEY" \
-H "Content-Type: application/json" \
-d '{
  "evaluations": [
    { "key": "new-checkout", "defaultValue": false },
    { "key": "checkout-heading", "defaultValue": "Checkout" }
  ],
  "context": {
    "user": { "id": "user_123" },
    "account": { "id": "account_456", "plan": "pro" }
  }
}'

Batch flags used by the same operation instead of making sequential requests. Keys within one batch must be unique. Send either evaluations or the compatibility flags form, not both.

Every evaluation should include a default matching the expected type. That value is the caller's failure policy when the flag is missing, archived, unconfigured, or incompatible.

Interpret the response

The response identifies the bound project and environment and returns one result for each requested key. Each result includes key, type, value, and reason.

Do not infer environment from local configuration. Verify the response environment during integration testing so a staging key cannot be deployed to production unnoticed.

Use the result reason for diagnostics. Keep normal application branching on the returned typed value. Do not log the entire response when values may contain sensitive application configuration.

Design context

Send only documented attributes required by active rules. Normalize IDs and enum values before the request. Missing attributes are rule misses, not request failures.

FeatureGate validates body size, number and length of flag keys, number of context fields, JSON size, and nesting depth. The generated reference is authoritative for current limits.

Raw context, targeting values, user identifiers, and resolved values are not stored as evaluation telemetry. Existing requested flags contribute only privacy-safe aggregate usage.

Timeout and fallback policy

Set a caller timeout shorter than the surrounding operation budget. On timeout or network failure, apply the explicit defaults locally and record a privacy-safe operational error.

Retry only when the operation can afford extra latency. Use bounded exponential backoff for network failures and 5xx. Respect retry information for 429.

Do not retry 400, 401, 403, or 413 without changing the request, key, configuration, or organisation state. Immediate repetition adds load without changing the outcome.

Error handling

Production checklist

• Reuse an HTTP client and connection pool.
• Batch related evaluations.
• Keep the runtime key in a server secret manager.
• Define typed defaults before integration.
• Bound timeout and retry behaviour.
• Avoid request and response body logging.
• Monitor request IDs, status classes, latency, and fallback activation.

See the generated POST /v1/evaluate reference for current wire shapes and Troubleshooting for symptom-led diagnosis.