Use this API to manage the Flipper-based feature flags used in the development of GitLab itself.

These endpoints support only boolean and percentage-of-time gate values, and require administrator authorization.

List all feature flags

GET /api/v4/features

Lists all feature flags for the instance.

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesFeature
401Unauthorized—
403Forbidden—

List all feature flag definitions

GET /api/v4/features/definitions

Lists all feature flag definitions.

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesFeatureDefinition
401Unauthorized—
403Forbidden—

Create or update a feature flag

POST /api/v4/features/{name}

Creates or updates a feature flag value. If a feature with the given name doesn’t exist yet, the operation creates one. The value can be a boolean or an integer to indicate percentage of time.

Parameters

NameTypeDescription
name
Path, required
StringName of the feature flag

Request body (application/json)

PropertyTypeDescription
endpointStringCaller ID identifying a code path, for example GET /api/v4/projects/:id or ProjectsController#show. Use a comma to separate multiple endpoint paths. Mutually exclusive with key
feature_groupStringName of the feature group. Mutually exclusive with key
forceBooleanIf true, skips feature flag validation checks, such as a YAML definition
groupStringGitLab group path, for example gitlab-org, or a comma-separated list of group paths. Mutually exclusive with key
keyStringRollout strategy for a percentage value. Omit it to apply the percentage to time. Mutually exclusive with feature_group, user, group, namespace, project, organization, repository, runner, endpoint
Allowed values: percentage_of_actors, percentage_of_time
namespaceStringGitLab group or user namespace path, for example john-doe, or a comma-separated list of namespace paths. Introduced in GitLab 15.0. Mutually exclusive with key
organizationStringOrganization ID or path, for example 1 or default, or a comma-separated list of organization IDs or paths. Mutually exclusive with key
projectStringProject path, for example gitlab-org/gitlab-foss, or a comma-separated list of project paths. Mutually exclusive with key
repositoryStringRepository path, for example gitlab-org/gitlab-test.git, gitlab-org/gitlab-test.wiki.git, or snippets/21.git. Use commas to separate multiple repository paths. Mutually exclusive with key
runnerStringRunner ID or a comma-separated list of runner IDs. Mutually exclusive with key
userStringGitLab username or a comma-separated list of usernames. Mutually exclusive with key
value
Required
String or integerValue to set for the feature flag. Use true or false to enable or disable it, or an integer for the percentage of time it should be enabled

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesFeature
400Bad request—
401Unauthorized—
403Forbidden—
404Not Found—

Delete a feature

DELETE /api/v4/features/{name}

Deletes a feature gate. Returns the same response if the feature gate does not exist.

Parameters

NameTypeDescription
name
Path, required
StringName of the feature flag

Responses

CodeDescriptionSchema
204Resource deleted—
400Bad Request—
404Not Found—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesFeature

PropertyTypeDescription
definitionAPIEntitiesFeatureDefinition—
gatesAPIEntitiesFeatureGate—
nameStringExample: experimental_feature
stateStringExample: off

APIEntitiesFeatureDefinition

PropertyTypeDescription
default_enabledBoolean—
feature_issue_urlString—
groupString—
intended_to_rollout_byString—
introduced_by_urlString—
log_state_changesBoolean—
milestoneString—
nameString—
rollout_issue_urlString—
typeString—

APIEntitiesFeatureGate

PropertyTypeDescription
keyStringExample: percentage_of_actors
valueIntegerExample: 34