> ## Documentation Index
> Fetch the complete documentation index at: https://feather.mupeni.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Evaluate Flag

> Evaluates a single feature flag for the provided context.

Returns the resolved flag value and evaluation reason from the edge bundle cache.

**Auth**: API key only (`Authorization: Bearer <key>`).

## Body

<ParamField body="flagKey" type="string" required>
  The flag key to evaluate.
</ParamField>

<ParamField body="context" type="object" required>
  Evaluation context.
</ParamField>

<ParamField body="context.userId" type="string">
  Stable user identifier.
</ParamField>

<ParamField body="context.anonymousId" type="string">
  Anonymous identifier when `userId` is not available.
</ParamField>

<ParamField body="context.attributes" type="Record<string, string | number | boolean>">
  Additional attributes used by flag rules.
</ParamField>

## Response

<ResponseField name="flagKey" type="string" required />

<ResponseField name="value" type="boolean | string | number | null" required />

<ResponseField name="reason" type="&#x22;DISABLED&#x22; | &#x22;RULE_MATCH&#x22; | &#x22;ROLLOUT&#x22; | &#x22;DEFAULT&#x22; | &#x22;FLAG_NOT_FOUND&#x22; | &#x22;ERROR&#x22;" required />

<ResponseField name="ruleId" type="string" />

<ResponseField name="variant" type="string" />

<ResponseField name="requestId" type="string" required />

<Info>
  Client keys (`pk_...`) cannot evaluate non-`clientSafe` flags. Those evaluations are masked as
  `FLAG_NOT_FOUND`.
</Info>

## Status codes

| Status | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| `200`  | Evaluation succeeded                                        |
| `400`  | Invalid JSON body (`INVALID_JSON`)                          |
| `401`  | Missing/invalid API key (`UNAUTHORIZED`, `INVALID_API_KEY`) |
| `422`  | Validation failed (`VALIDATION_ERROR`)                      |
| `429`  | Rate-limited (`RATE_LIMITED`)                               |
| `503`  | Bundle unavailable; returns `reason: "ERROR"`               |

<RequestExample>
  ```bash theme={null}
  curl -X POST https://fly.feather.mupeni.dev/v1/evaluate \
    -H "Authorization: Bearer <api_key>" \
    -H "Content-Type: application/json" \
    -d '{
      "flagKey": "new-checkout",
      "context": {
        "userId": "user_123",
        "attributes": { "country": "DE", "plan": "pro" }
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "flagKey": "new-checkout",
    "value": true,
    "reason": "RULE_MATCH",
    "ruleId": "rule_beta",
    "requestId": "9fd3e4bc-5f2a-4ba2-b7f4-8a74054b8132"
  }
  ```

  ```json 503 theme={null}
  {
    "flagKey": "new-checkout",
    "value": null,
    "reason": "ERROR"
  }
  ```
</ResponseExample>