Flags
Flags
Create and manage typed feature flags and per-environment targeting
Overview
The Flags resource manages typed feature flags within a project. A flag has a stable key, a display name, an optional description, a type, and one or more named variations. Supported flag types are boolean, string, number, and json.
Creating a flag also creates a default disabled configuration in every environment. Use the flag endpoints to manage the flag definition and its variations. Use the targeting endpoint separately to replace the configuration for one environment, including its enabled state, fallback variations, and ordered targeting rules.
Note:
Targeting is configured per environment. Updating a flag's metadata or variations with PATCH does not replace its targeting configuration; use the dedicated targeting endpoint for that operation.
Schema
The following fields are accepted by the flag definition and targeting requests or returned by the flag endpoints. A variation is referenced by its unique key; the complete variation object is defined by the API's variation schema.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Create: yes; response: yes | Stable flag key referenced by clients, such as new-checkout. |
name | string | Create: yes; update: optional; response: yes | Flag name. The API accepts 1–120 characters. |
description | string | Create: optional; update: optional; response: nullable | Additional flag description. The API accepts up to 500 characters. |
type | boolean | string | number | json | Create: yes; response: yes | Type of value the flag serves. |
variations | array of variation objects | Create: yes; update: optional; response: yes | Named values the flag can serve. The array must contain at least one variation, and variation keys must be unique. |
id | string | Response: yes | Flag identifier. |
projectId | string | Response: yes | Identifier of the project that owns the flag. |
configs | array of environment configuration objects | Response: yes | Per-environment configurations embedded in the flag response. |
createdAt | string | Response: yes | Flag creation timestamp. |
updatedAt | string | Response: yes | Time the flag was last updated. |
environment | string | Targeting request: yes | Environment key whose targeting configuration is replaced. |
environmentKey | string | Configuration response: yes | Environment key for a returned configuration. |
enabled | boolean | Targeting request and configuration response: yes | Whether the flag is enabled in the environment. |
defaultVariationKey | string | Targeting request and configuration response: yes | Variation key served when targeting rules fall through. |
offVariationKey | string | Targeting request and configuration response: yes | Variation key served when the flag is disabled. |
rules | array of targeting rule objects | Targeting request and configuration response: yes | Ordered targeting rules for the environment. |
Endpoints
All paths use the project identifier in {projectId}. Flag keys are supplied in {flagKey} for operations on an existing flag.
| Method | Path | Description |
|---|---|---|
POST | /v1/projects/{projectId}/flags | Create a typed flag with named variations. A default disabled configuration is created in every environment. |
GET | /v1/projects/{projectId}/flags | List the flags for a project. |
GET | /v1/projects/{projectId}/flags/{flagKey} | Fetch one flag by key within a project, including its per-environment configurations. |
PATCH | /v1/projects/{projectId}/flags/{flagKey} | Update a flag's name, description, or variations. Targeting is updated separately. |
DELETE | /v1/projects/{projectId}/flags/{flagKey} | Delete a flag by key. |
PUT | /v1/projects/{projectId}/flags/{flagKey}/targeting | Replace the enabled state, default and off variation keys, and ordered targeting rules for the flag in one environment. |