API reference

Evaluate

Evaluate flags over HTTP — for languages without an SDK, or for debugging.

Evaluate flags

POST/evaluate

Evaluates one or more flags for a context, using an SDK key instead of an API token. Served from the edge in ~10 ms.

Headers

Authorizationstringrequired: Bearer <sdk key> — server or client key.

Body parameters

flagsstring[]optional: Keys to evaluate. Omit for all flags.
contextobjectrequired: Evaluation context; user.id is required.
detailbooleanoptionalDefault: false: Include the reason for each result.

Request

Terminal

curl -X POST https://edge.shoal.dev/v2/evaluate \
  -H "Authorization: Bearer $SHOAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "flags": ["new-checkout"], "context": { "user": { "id": "u_42", "plan": "pro" } }, "detail": true }'

TypeScript

const res = await fetch("https://edge.shoal.dev/v2/evaluate", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SHOAL_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ flags: ["new-checkout"], context: { user: { id: "u_42" } } }),
});

Python

import requests
requests.post("https://edge.shoal.dev/v2/evaluate",
  headers={"Authorization": f"Bearer {key}"},
  json={"flags": ["new-checkout"], "context": {"user": {"id": "u_42"}}})

Response

JSON

{
  "values": { "new-checkout": true },
  "reasons": { "new-checkout": { "kind": "RULE_MATCH", "ruleIndex": 0 } }
}

JSON

{
  "error": { "code": "invalid_context", "message": "context.user.id is required" }
}