Ordnary

Docs Ordnary Web Services Ordnary Halyard

Flags API

The HTTPS API your app uses: evaluating flags for a context, fetching an environment's configuration to evaluate locally, and errors.

6 min readIntermediate

Every request goes to https://halyard.ordnary.com/v1 and carries an environment's SDK key. CORS is open, so browsers can call it directly.

Authentication

http
Authorization: Bearer ofk_...

Find the keys in the console, in your project under SDK keys. Rotating a key there stops the old one at once.

Evaluate flags

POST/v1/evaluate

Evaluates every flag of the environment for one context, or only the ones you list.

contextobjectRequired
Who is asking. key is the stable id rollouts use; every other attribute is up to you.
flagsarray
Flag keys to evaluate. Leave it out to get every flag.
POST/v1/evaluate
{
  "context": { "key": "user-123", "email": "ada@example.com", "country": "NL" },
  "flags": ["new-checkout"]
}
  • value any

    The variation the context gets: a boolean, string, number or JSON value.

  • variation integer

    Its position in the flag's variations, starting at 0.

  • reason string

    off (the flag is off), rule_match (a rule decided) or default.

  • ruleId string

    The rule that matched, with rule_match.

Fetch the configuration

GET/v1/flags

Every flag of the environment with its variations, state, rules and default, to evaluate locally.

A server that serves many users can fetch this every few seconds and evaluate in memory instead of making a request per user. Evaluate the way the server does: off variation when off, then rules from top to bottom, then the default.

Response
{
  "project": "Web app",
  "environment": "production",
  "flags": {
    "new-checkout": {
      "kind": "boolean",
      "variations": [true, false],
      "enabled": true,
      "offVariation": 1,
      "default": { "rollout": { "variations": [{ "variation": 0, "weight": 10 }, { "variation": 1, "weight": 90 }] } },
      "rules": [
        { "id": "staff", "clauses": [{ "attribute": "email", "operator": "ends_with", "values": ["@yourcompany.com"] }], "serve": { "variation": 0 } }
      ],
      "version": 4
    }
  }
}

Rollout bucketing

To place a context in a rollout, take the SHA-1 of "<flag key>.<context key>", read its first 15 hex digits as a number and divide by 16^15. Multiply by 100 for a percentage, then walk the weights in order until their sum passes it. This is exactly what the server does, so local and server evaluation agree.

Errors

400
invalid_body: the request body is not the JSON described above.
401
invalid_key: the SDK key is missing, wrong or has been rotated.
404
not_found: an endpoint other than GET /v1/flags or POST /v1/evaluate.
Was this page helpful?
Updated 2 November 2026 Suggest an edit

Choose which cookies Ordnary may use. You can change this at any time via Cookie settings at the bottom of every page.