Skip to main content
When your application calls POST /api/v1/evaluate, Togul checks the flag’s state and any active targeting rules, then returns a boolean value and a reason explaining why that value was returned.

​
Authentication

The evaluation endpoint requires an X-API-Key header with a server or sdk scoped API key. Keys are environment-scoped, so you must also provide the matching environment_key in the request body. 
curl -X POST http://localhost:8080/api/v1/evaluate \
  -H "X-API-Key: tgl_srv_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "flag_key": "new-dashboard",
    "environment_key": "production",
    "context": {
      "user_id": "user-123",
      "country": "TR",
      "plan": "premium"
    }
  }'

​
Request body

FieldTypeRequiredDescription
flag_keystringYesThe key of the flag to evaluate
environment_keystringYesThe key of the environment the flag belongs to
contextobjectNoKey-value pairs of strings used for rule targeting
The context object is a flat map of string keys to string values. Common fields include user_id, country, and plan, but you can include any attribute your targeting rules reference. 
{
  "flag_key": "new-dashboard",
  "environment_key": "production",
  "context": {
    "user_id": "user-123",
    "country": "TR",
    "plan": "premium"
  }
}

​
Evaluation order

Togul evaluates each flag using the following order:
  1. Flag disabled — If the flag’s enabled field is false, Togul immediately returns default_value with reason disabled. No rules are checked.
  2. Active rules in priority order — Active rules are checked from lowest priority number to highest. The first rule that matches the provided context determines the result.
  3. Rule match — When a rule matches, Togul returns the rule’s return_value with reason rule_match.
  4. No match — If no active rule matches, Togul returns default_value with reason default.

​
Response schema

Every evaluation returns an EvaluateResponse object:
FieldTypeDescription
flag_keystringThe key of the evaluated flag
enabledbooleanWhether the flag is currently enabled
valuebooleanThe resolved value for this evaluation
reasonstringOne of disabled, rule_match, or default

​
Example responses

{
  "flag_key": "new-dashboard",
  "enabled": true,
  "value": true,
  "reason": "rule_match"
}

​
Quotas and regional constraints

Evaluation quota — Each evaluation request counts against your subscription’s monthly evaluation quota. If the quota is exhausted, the endpoint returns 403 Forbidden. Multi-region — In non-primary regions, the target environment must be explicitly enabled for that region before evaluation requests will succeed. Requests to an environment that is not enabled in the current region return 403 Forbidden.

​
Error reference

StatusCause
401 UnauthorizedThe X-API-Key header is missing, invalid, or the key has been revoked
403 ForbiddenMonthly evaluation quota exceeded, or the environment is not enabled in the current region
404 Not FoundThe specified flag key or environment key does not exist

Build docs developers (and LLMs) love

Get started for freeTalk to us