Feature Flags API Reference

All flag API endpoints are scoped to an organization and project. They follow the response envelope pattern: { data: ... } on success or { error: "message" } on failure.

Flags

List Flags

GET /api/orgs/:orgId/projects/:projectId/flags

Returns all flags in the project with their type, status, stale indicator, variations, and per-environment toggle state.

Create Flag

POST /api/orgs/:orgId/projects/:projectId/flags

Permission: createExperiments

1{
2  "name": "New Checkout Flow",
3  "key": "new_checkout",
4  "type": "BOOLEAN",
5  "description": "Enable the redesigned checkout experience",
6  "variations": [
7    { "name": "Off", "key": "off", "value": "false" },
8    { "name": "On", "key": "on", "value": "true" }
9  ],
10  "defaultVariationKey": "off"
11}

The flag is created in DRAFT status with all environments disabled. Boolean flags must have exactly two variations with values "true" and "false".

Get Flag Detail

GET /api/orgs/:orgId/projects/:projectId/flags/:flagId

Returns the full flag with variations, environment configs, rules, overrides, and audience references.

Update Flag

PATCH /api/orgs/:orgId/projects/:projectId/flags/:flagId

Update name and description. The flag key and type cannot be changed after creation.

Delete Flag

DELETE /api/orgs/:orgId/projects/:projectId/flags/:flagId

Only flags in DRAFT or ARCHIVED status can be deleted.

Archive Flag

POST /api/orgs/:orgId/projects/:projectId/flags/:flagId/archive

Sets the flag status to ARCHIVED and marks all active environments as having pending changes.

Variations

Update Variations

PUT /api/orgs/:orgId/projects/:projectId/flags/:flagId/variations

Bulk update, add, or remove variations. Variations referenced by rules or overrides cannot be removed (returns 422).

1{
2  "variations": [
3    { "id": "existing_id", "name": "Blue", "key": "blue", "value": "\"blue\"" },
4    { "name": "Green", "key": "green", "value": "\"green\"" }
5  ],
6  "defaultVariationKey": "blue"
7}

Environment Config

Toggle Flag / Update Config

PATCH /api/orgs/:orgId/projects/:projectId/flags/:flagId/envs/:envId

Toggle the flag on/off, change the default variation, or configure scheduling. Requires publishProduction permission for production environments.

1{
2  "enabled": true,
3  "defaultVariationId": "var_abc123",
4  "schedulingEnabled": true,
5  "scheduledEnableAt": "2025-03-15T09:00:00Z",
6  "timezone": "America/New_York"
7}

Rules

Create Rule

POST /api/orgs/:orgId/projects/:projectId/flags/:flagId/envs/:envId/rules

1{
2  "type": "AB_TEST",
3  "name": "Checkout button colour test",
4  "trafficAllocation": 1.0,
5  "variations": [
6    { "variationId": "var_control", "percentage": 0.5 },
7    { "variationId": "var_treatment", "percentage": 0.5 }
8  ],
9  "audienceIds": [],
10  "hashAttribute": "userId"
11}

Update Rule

PATCH /api/orgs/:orgId/projects/:projectId/flags/:flagId/envs/:envId/rules/:ruleId

Delete Rule

DELETE /api/orgs/:orgId/projects/:projectId/flags/:flagId/envs/:envId/rules/:ruleId

Reorder Rules

PUT /api/orgs/:orgId/projects/:projectId/flags/:flagId/envs/:envId/rules/reorder

A/B Test rules are evaluated before Targeted Delivery rules. Within the same type, rules are evaluated in sort order.

Overrides

Update Overrides

PUT /api/orgs/:orgId/projects/:projectId/flags/:flagId/envs/:envId/overrides

Bulk replace all user overrides for a flag in an environment. Overrides are evaluated before all rules.

Environments

List Environments

GET /api/orgs/:orgId/projects/:projectId/environments

Create Environment

POST /api/orgs/:orgId/projects/:projectId/environments

Publish Environment

POST /api/orgs/:orgId/projects/:projectId/environments/:envId/publish

Generates and publishes the flag datafile for this environment. Sets hasPendingChanges to false on all flag configs.

Events

List Events

GET /api/orgs/:orgId/projects/:projectId/flag-events

Create Event

POST /api/orgs/:orgId/projects/:projectId/flag-events

1{
2  "name": "Purchase",
3  "key": "purchase",
4  "description": "User completes a purchase",
5  "type": "CONVERSION"
6}

Event types: CONVERSION (binary yes/no) or NUMERIC (mean value, e.g., revenue).

SDK Heartbeat

The SDK sends a heartbeat after each successful datafile fetch. This is handled automatically — no manual integration needed.

Send Heartbeat

POST /api/sdk/heartbeat

Public endpoint — no authentication required. The SDK key identifies the environment.

Request Body

1{
2  "sdkKey": "sdk_prod_abc123",
3  "sdkType": "@avsbhq/browser",
4  "sdkVersion": "0.2.0"
5}

Response

Returns { "success": true } on success. Returns 404 for an unknown SDK key.