- Sells as: the
config-flags product (a product-scoped API key). This capability has no separate product-face contract — its public product route reuses the capability contract below; see the Edge route table's Product face row.
Runtime-config capability — a durable, org-scoped feature-flag registry with a deterministic-hash percentage-rollout evaluator (fail-closed on unknown flags, per-site override, manual override, explicit target-user/org allowlist) PLUS a typed settings key-value store. Products stop each re-rolling a flag engine + a settings store; they evaluate flags and read/write config over this one capability. I4: own Postgres store, never a product Mongo.
- Group: Governance & platform
- Contract:
contracts/config-flags/v1/openapi.yaml
- Console: Manage the
config-flags product in the console →
- Runbook: operational checklist for
config-flags — internal (Vagary Labs ops; not part of this public site): docs/runbooks/capability-operations.md#config-flags
- Public base:
https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
- Auth: a product API key (
vgk_…) issued from the console — Authorization: Bearer vgk_…
- Product face (customer-keyed):
https://api.vagarylabs.com/product/v1/flags/evaluate
Edge route table
The routes this capability actually serves on the public edge — live-synced from GET https://api.vagarylabs.com/product/v1/_meta/catalog (snapshot v1). The metric is the request-granularity billing counter; the scope is the key permission required.
Product face (customer-keyed)
| Method | Path | Metric | Scope |
|---|
POST | /product/v1/flags/evaluate | flag_evaluations | read |
Endpoints
| Method | Path | Summary |
|---|
POST | /v1/flags/evaluate | Evaluate one flag for the caller's org (fail-closed; unknown flag → false) |
POST | /v1/flags/evaluate-batch | Evaluate many flags in one round-trip |
GET | /v1/flags | List the org's flag definitions |
GET | /v1/flags/{name} | The flag definition for one name (optionally a per-site override) or 404 |
PUT | /v1/flags/{name} | Register or update a flag definition (idempotent upsert) |
DELETE | /v1/flags/{name} | Remove a flag definition (optionally a specific per-site override) |
GET | /v1/settings | List settings (optionally by category); sensitive values redacted |
GET | /v1/settings/{category}/{key} | One setting value (sensitive value redacted) or 404 |
PUT | /v1/settings/{category}/{key} | Upsert a typed setting value |
DELETE | /v1/settings/{category}/{key} | Remove a setting |
GET | /health | liveness |
GET | /metrics | Prometheus |
Schemas
EvaluateRequest
| Field | Type | Description |
|---|
organization_id | string | product-tier tenant (I6) |
flag | string | flag name (dotted namespace) |
user_id | string | user to bucket for percentage rollout; omit for a no-user default eval |
site_id | string | per-site override selector; omit for the global definition |
EvaluateResult
| Field | Type | Description |
|---|
flag | string | |
enabled | boolean | |
EvaluateBatchRequest
| Field | Type | Description |
|---|
organization_id | string | |
flags | array | |
user_id | string | |
site_id | string | |
EvaluateBatchResult
| Field | Type | Description |
|---|
results | object | flag name → enabled |
FlagDefinition
| Field | Type | Description |
|---|
name | string | |
site_id | string | '' = global definition; non-empty = per-site override |
default_enabled | boolean | |
rollout_percentage | number | |
override | ['boolean', 'null'] | manual on/off; null = no override |
target_users | array | explicit user allowlist (wins over rollout) |
target_orgs | array | explicit org allowlist (wins over rollout) |
description | string | |
FlagUpsert
| Field | Type | Description |
|---|
organization_id | string | |
site_id | string | |
default_enabled | boolean | |
rollout_percentage | number | |
override | ['boolean', 'null'] | |
target_users | array | |
target_orgs | array | |
description | string | |
FlagList
| Field | Type | Description |
|---|
flags | array | |
Setting
| Field | Type | Description |
|---|
category | string | |
key | string | |
value | object | any JSON type (bool/int/string/object); sensitive keys are redacted on read |
Generated by scripts/gen-capability-docs.py from contracts/config-flags/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page. The Edge route table section is synced from the live edge catalog snapshot (v1) — re-sync with python3 scripts/sync-edge-catalog.py.