Config flags
Sellable product
This capability is granted by an API key scoped to the `` product (product face). See the product reference below.
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 - Public base:
https://api.vagarylabs.com(the consolidated API gateway — one host, per-brand siblingapi.<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
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.