Feature Flags Resolve, toggle, and manage feature flags for organizations and platform-wide rollouts.
All endpoints require a Bearer token (Authorization: Bearer aira_live_xxxxx) unless noted otherwise. Base URL: https://api.airaproof.com/api/v1
The feature flags API has two sets of endpoints:
Org routes (/api/v1/feature-flags/...) -- authenticated with a Bearer token, scoped to the caller's organization.Admin routes (/api/v1/admin/feature-flags/...) -- require the X-Admin-Key header for superadmin access.
GET /api/v1/feature-flags Authorization : Bearer aira_live_xxxxx Returns all feature flags resolved for the authenticated organization. Each flag is evaluated using three-tier resolution: per-org override, global enablement with rollout percentage, and self-hosted environment variable fallback.
curl https://api.airaproof.com/api/v1/feature-flags \ -H "Authorization: Bearer aira_live_xxxxx" { "flags" : { "advanced_drift" : true , "beta_dashboard" : false , "consensus_v2" : true }, "request_id" : "req_01J9E..." } Field Type Description flagsobject Map of flag keys to their resolved boolean values for the current org request_idstring Request ID for tracing
PUT /api/v1/feature-flags/{key} Authorization : Bearer aira_live_xxxxx Enables or disables a beta feature flag for the authenticated organization. Requires the org admin role. If the flag does not exist yet (common on self-hosted instances), enabling it will create it automatically.
Parameter Type Required Description keystring Yes The feature flag key
Field Type Required Description enabledboolean Yes Whether to enable (true) or disable (false) the flag for this org
curl -X PUT https://api.airaproof.com/api/v1/feature-flags/beta_dashboard \ -H "Authorization: Bearer aira_live_xxxxx" \ -H "Content-Type: application/json" \ -d '{ "enabled": true }' { "key" : "beta_dashboard" , "enabled" : true , "request_id" : "req_01J9F..." } Field Type Description keystring The feature flag key enabledboolean The new state of the flag for this org request_idstring Request ID for tracing
GET /api/v1/admin/feature-flags X-Admin-Key : <admin_api_key> Returns all feature flags in the system. Requires the X-Admin-Key header.
curl https://api.airaproof.com/api/v1/admin/feature-flags \ -H "X-Admin-Key: your-admin-key" [ { "id" : "550e8400-e29b-41d4-a716-446655440000" , "key" : "advanced_drift" , "description" : "Enable advanced drift detection with KL divergence" , "enabled_global" : true , "rollout_percentage" : 100 , "enabled_org_ids" : [], "created_at" : "2026-06-01T12:00:00+00:00" , "updated_at" : "2026-06-15T09:30:00+00:00" }, { "id" : "660e8400-e29b-41d4-a716-446655440001" , "key" : "beta_dashboard" , "description" : "New dashboard UI beta" , "enabled_global" : false , "rollout_percentage" : 100 , "enabled_org_ids" : [ "org_01J9A..." , "org_01J9B..." ], "created_at" : "2026-06-10T08:00:00+00:00" , "updated_at" : "2026-06-10T08:00:00+00:00" } ] POST /api/v1/admin/feature-flags X-Admin-Key : <admin_api_key> Creates a new feature flag. The key must be unique and match the pattern ^[a-z][a-z0-9_]{1,98}[a-z0-9]$ (lowercase letters, digits, and underscores; 3--100 characters; must start with a letter and end with a letter or digit).
Field Type Required Description keystring Yes Unique flag key (lowercase, underscores allowed, 3--100 chars) descriptionstring No Human-readable description enabled_globalboolean No Whether the flag is globally enabled (default: false) rollout_percentageinteger No Percentage of orgs to roll out to when globally enabled, 0--100 (default: 100) enabled_org_idsstring[] No List of org UUIDs to explicitly enable the flag for (default: [])
curl -X POST https://api.airaproof.com/api/v1/admin/feature-flags \ -H "X-Admin-Key: your-admin-key" \ -H "Content-Type: application/json" \ -d '{ "key": "consensus_v2", "description": "V2 consensus scoring algorithm", "enabled_global": false, "rollout_percentage": 50, "enabled_org_ids": ["org_01J9A..."] }' { "id" : "770e8400-e29b-41d4-a716-446655440002" , "key" : "consensus_v2" , "description" : "V2 consensus scoring algorithm" , "enabled_global" : false , "rollout_percentage" : 50 , "enabled_org_ids" : [ "org_01J9A..." ], "created_at" : "2026-07-01T10:00:00+00:00" , "updated_at" : "2026-07-01T10:00:00+00:00" } Status Description 409 A flag with this key already exists
PUT /api/v1/admin/feature-flags/{key} X-Admin-Key : <admin_api_key> Updates an existing feature flag. Only the fields you provide will be changed; omitted fields are left unchanged.
Parameter Type Required Description keystring Yes The feature flag key
Field Type Required Description descriptionstring No Updated description enabled_globalboolean No Updated global enablement rollout_percentageinteger No Updated rollout percentage (0--100) enabled_org_idsstring[] No Updated list of explicitly enabled org UUIDs (replaces the existing list)
curl -X PUT https://api.airaproof.com/api/v1/admin/feature-flags/consensus_v2 \ -H "X-Admin-Key: your-admin-key" \ -H "Content-Type: application/json" \ -d '{ "enabled_global": true, "rollout_percentage": 25 }' { "id" : "770e8400-e29b-41d4-a716-446655440002" , "key" : "consensus_v2" , "description" : "V2 consensus scoring algorithm" , "enabled_global" : true , "rollout_percentage" : 25 , "enabled_org_ids" : [ "org_01J9A..." ], "created_at" : "2026-07-01T10:00:00+00:00" , "updated_at" : "2026-07-05T14:00:00+00:00" } Status Description 404 Flag not found
DELETE /api/v1/admin/feature-flags/{key} X-Admin-Key : <admin_api_key> Deletes a feature flag. If the flag does not exist, the request completes silently.
Parameter Type Required Description keystring Yes The feature flag key
curl -X DELETE https://api.airaproof.com/api/v1/admin/feature-flags/consensus_v2 \ -H "X-Admin-Key: your-admin-key" No response body.
POST /api/v1/admin/feature-flags/{key}/enable-org/{org_uuid} X-Admin-Key : <admin_api_key> Adds an organization to a flag's enabled_org_ids list. This is an additive operation -- existing org IDs are preserved.
Parameter Type Required Description keystring Yes The feature flag key org_uuidstring Yes The UUID of the organization to enable
curl -X POST https://api.airaproof.com/api/v1/admin/feature-flags/beta_dashboard/enable-org/org_01J9C... \ -H "X-Admin-Key: your-admin-key" { "id" : "660e8400-e29b-41d4-a716-446655440001" , "key" : "beta_dashboard" , "description" : "New dashboard UI beta" , "enabled_global" : false , "rollout_percentage" : 100 , "enabled_org_ids" : [ "org_01J9A..." , "org_01J9B..." , "org_01J9C..." ], "created_at" : "2026-06-10T08:00:00+00:00" , "updated_at" : "2026-07-05T15:00:00+00:00" } Status Description 404 Flag not found
POST /api/v1/admin/feature-flags/{key}/disable-org/{org_uuid} X-Admin-Key : <admin_api_key> Removes an organization from a flag's enabled_org_ids list.
Parameter Type Required Description keystring Yes The feature flag key org_uuidstring Yes The UUID of the organization to disable
curl -X POST https://api.airaproof.com/api/v1/admin/feature-flags/beta_dashboard/disable-org/org_01J9C... \ -H "X-Admin-Key: your-admin-key" { "id" : "660e8400-e29b-41d4-a716-446655440001" , "key" : "beta_dashboard" , "description" : "New dashboard UI beta" , "enabled_global" : false , "rollout_percentage" : 100 , "enabled_org_ids" : [ "org_01J9A..." , "org_01J9B..." ], "created_at" : "2026-06-10T08:00:00+00:00" , "updated_at" : "2026-07-05T15:30:00+00:00" } Status Description 404 Flag not found
All admin endpoints that return a flag use this shape:
Field Type Description idstring Flag UUID keystring Unique flag key descriptionstring | null Human-readable description enabled_globalboolean Whether the flag is globally enabled rollout_percentageinteger Percentage of orgs included in global rollout (0--100) enabled_org_idsstring[] Org UUIDs explicitly enabled regardless of global/rollout state created_atstring Creation timestamp (ISO 8601) updated_atstring Last update timestamp (ISO 8601)
When resolving a flag for a specific organization, the system uses three-tier resolution:
Per-org override -- if the org's UUID is in enabled_org_ids, the flag is true.Global + rollout -- if enabled_global is true, a deterministic hash of the org UUID is checked against rollout_percentage to decide inclusion.Self-hosted fallback -- on self-hosted deployments, if the flag does not exist in the database, the environment variable ENABLE_{KEY} (uppercased) is checked.