# Evaluate over HTTP

Batch typed server-side decisions through the hosted evaluation API.

`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

#### terminal
```sh
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

| Status | Meaning                                                 | Response                                      |
| ------ | ------------------------------------------------------- | --------------------------------------------- |
| `400`  | Invalid body, duplicate keys, type, or context          | Correct the caller                            |
| `401`  | Missing, malformed, unknown, or revoked key             | Replace the credential                        |
| `403`  | Scope, binding, origin, exposure, or offboarding policy | Inspect the exact error code                  |
| `413`  | Body exceeds a request-size guardrail                   | Reduce the batch or context                   |
| `429`  | Rate limit exceeded                                     | Respect retry information and reduce pressure |
| `5xx`  | Transient hosted failure                                | Use defaults and bounded retry                |

## 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](/docs/api/reference/runtime/evaluate) for current
wire shapes and [Troubleshooting](/docs/operate/troubleshooting-and-limits) for symptom-led diagnosis.