API reference

Read path (OFREP)

Guarded by the read API key (x-api-key header). Returns evaluated booleans only.

POST /ofrep/v1/evaluate/flags

Evaluate every flag for a context.

curl -X POST https://team-flags.you.workers.dev/ofrep/v1/evaluate/flags \
  -H "x-api-key: $READ_KEY" -H "content-type: application/json" \
  -d '{ "context": { "targetingKey": "user-1", "plan": "beta" } }'

{ "flags": [{ "key": "new-checkout", "value": true, "reason": "DEFAULT", "variant": "on" }] }

POST /ofrep/v1/evaluate/flags/{key}

Evaluate a single flag. Returns 404 with errorCode: FLAG_NOT_FOUND for an unknown key.

Admin path

Guarded by the admin verifier (bearer token or OIDC). This is Flaghoist’s own versioned API: build dashboards, scripts, and integrations against it.

Method	Path	Purpose
GET	/api/v1/flags	List all flags
GET	/api/v1/flags/:key	Get one flag
PUT	/api/v1/flags/:key	Create or replace a flag
DELETE	/api/v1/flags/:key	Delete a flag

The unversioned /flags paths remain as a legacy alias of /api/v1/flags.

PUT is a full replace (creation metadata is preserved). Send the complete desired state:

curl -X PUT https://team-flags.you.workers.dev/api/v1/flags/new-checkout \
  -H "authorization: Bearer $ADMIN_TOKEN" -H "content-type: application/json" \
  -d '{
    "enabled": true,
    "rollout": { "percentage": 25 },
    "description": "Redesigned checkout",
    "rules": [
      {
        "conditions": [{ "attribute": "plan", "operator": "eq", "value": "beta" }],
        "result": { "enabled": true, "rollout": { "percentage": 50 } }
      }
    ]
  }'

Other endpoints

Method	Path	Auth	Purpose
GET	/health	none	Health check
GET	/admin	none	The dashboard SPA (if configured)
GET	/api/v1/openapi.json	none	The OpenAPI 3.1 spec (see below)

Flag schema

interface FeatureFlag {
  key: string
  enabled: boolean
  rollout: { percentage: number } // the default rule
  rules?: TargetingRule[] // ordered, first match wins
  description: string
  metadata: { createdBy: string; createdAt: string; updatedBy: string; updatedAt: string }
}

Operators available in conditions: eq, neq, in, notIn, contains, startsWith, endsWith, gt, gte, lt, lte, semverGte, semverLt.

OpenAPI

Every server describes itself. Fetch the machine-readable spec from a running server:

curl https://team-flags.you.workers.dev/api/v1/openapi.json

It is an OpenAPI 3.1 document covering the admin API, the OFREP read endpoints, and the schemas above, so you can point Swagger UI, Postman, or a client generator at it. The same document is exported from the package for build-time tooling:

import { openApiDocument } from '@flaghoist/server'