Use this API to manage a project’s feature flags and the user lists that scope them to particular users.

These endpoints require the Developer, Maintainer, or Owner role.

List all feature flags for a project

GET /api/v4/projects/{id}/feature_flags

Lists all feature flags of the requested project. Use the page and per_page pagination parameters to control the pagination of results.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
scope
Query		StringFilter feature flags by condition
Allowed values: enabled, disabled
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesFeatureFlag
400Bad Request—
401Unauthorized—
404Not found—

Create a feature flag

POST /api/v4/projects/{id}/feature_flags

Creates a feature flag for a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
activeBooleanIf true, the feature flag is active
Default: true
descriptionStringDescription of the feature flag
name
Required		StringName of the feature flag
strategiesArray of objectsArray of feature flag strategies
strategies[].name
Required		StringName of the strategy. Can be default, gradualRolloutUserId, userWithId, gitlabUserList, or flexibleRollout
strategies[].parametersObjectStrategy parameters as a JSON-formatted string, for example {"userIds":"user1"}
strategies[].scopesArray of objectsArray of scopes for the strategy
strategies[].scopes[].environment_scope
Required		StringEnvironment scope of the scope
strategies[].user_list_idIntegerID of the feature flag user list. Applies only if the strategy is gitlabUserList

Responses

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

Retrieve a feature flag

GET /api/v4/projects/{id}/feature_flags/{feature_flag_name}

Retrieves a specified feature flag.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
feature_flag_name
Path, required		StringName of the feature flag

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureFlag
400Bad Request—
401Unauthorized—
404Not found—

Update a feature flag

PUT /api/v4/projects/{id}/feature_flags/{feature_flag_name}

Updates a specified feature flag.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
feature_flag_name
Path, required		StringName of the feature flag

Request body (application/json)

PropertyTypeDescription
activeBooleanIf true, the feature flag is active
descriptionStringDescription of the feature flag
nameStringNew name of the feature flag
strategiesArray of objectsArray of feature flag strategies
strategies[]._destroyBooleanIf true, deletes the strategy
strategies[].idIntegerID of the feature flag strategy
strategies[].nameStringName of the strategy
strategies[].parametersObjectStrategy parameters as a JSON-formatted string, for example {"userIds":"user1"}
strategies[].scopesArray of objectsArray of scopes for the strategy
strategies[].scopes[]._destroyBooleanIf true, deletes the scope
strategies[].scopes[].environment_scopeStringEnvironment scope of the scope
strategies[].scopes[].idIntegerID of the scope
strategies[].user_list_idIntegerID of the feature flag user list. Applies only if the strategy is gitlabUserList

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureFlag
400Bad Request—
401Unauthorized—
403Forbidden—
404Not found—
422Unprocessable entity—

Delete a feature flag

DELETE /api/v4/projects/{id}/feature_flags/{feature_flag_name}

Deletes a specified feature flag.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
feature_flag_name
Path, required		StringName of the feature flag

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureFlag
400Bad Request—
401Unauthorized—
403Forbidden—
404Not found—

Retrieve feature flag settings

GET /api/v4/projects/{id}/feature_flags_settings

Retrieves the feature flag settings of a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureFlagSettings
400Bad Request—
401Unauthorized—
404Not found—

Update feature flag settings

PUT /api/v4/projects/{id}/feature_flags_settings

Updates the feature flag settings of a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
minimum_role
Required		StringMinimum role required to create, update, toggle, and delete feature flags
Allowed values: no_one_allowed, developer, maintainer, owner
Minimum length: 1

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureFlagSettings
400Bad request—
401Unauthorized—
403Forbidden—
404Not found—

List all feature flag user lists for a project

GET /api/v4/projects/{id}/feature_flags_user_lists

Lists all feature flag user lists for a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
search
Query		StringReturn user lists matching the search criteria
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesFeatureFlagUserList
400Bad Request—
401Unauthorized—
404Not found—

Create a feature flag user list

POST /api/v4/projects/{id}/feature_flags_user_lists

Creates a feature flag user list in a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
name
Required		StringThe name of the list
user_xids
Required		StringA comma separated list of external user ids

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesFeatureFlagUserList
400Bad request—
401Unauthorized—
404Not found—

Retrieve a feature flag user list

GET /api/v4/projects/{id}/feature_flags_user_lists/{iid}

Retrieves a specified feature flag user list.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
iid
Path, required		String or integerThe internal ID of the project’s feature flag user list

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureFlagUserList
400Bad Request—
401Unauthorized—
404Not found—

Update a feature flag user list

PUT /api/v4/projects/{id}/feature_flags_user_lists/{iid}

Updates a specified feature flag user list.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
iid
Path, required		String or integerThe internal ID of the project’s feature flag user list

Request body (application/json)

PropertyTypeDescription
nameStringThe name of the list
user_xidsStringA comma separated list of external user ids

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureFlagUserList
400Bad request—
401Unauthorized—
404Not found—

Delete feature flag user list

DELETE /api/v4/projects/{id}/feature_flags_user_lists/{iid}

Deletes a specified feature flag user list.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
iid
Path, required		String or integerThe internal ID of the project’s feature flag user list

Responses

CodeDescriptionSchema
204Resource deleted—
400Bad Request—
401Unauthorized—
404Not found—
409Conflict—

Schemas

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

APIEntitiesFeatureFlag

PropertyTypeDescription
activeBoolean—
created_atString (date-time)Example: 2019-11-04T08:13:51.423Z
descriptionStringExample: merge train feature flag
nameStringExample: merge_train
scopesArray—
strategiesAPIEntitiesFeatureFlagStrategy—
updated_atString (date-time)Example: 2019-11-04T08:13:51.423Z
versionStringExample: new_version_flag

APIEntitiesFeatureFlagBasicUserList

PropertyTypeDescription
idInteger (int64)Example: 1
iidIntegerExample: 1
nameStringExample: user_list
user_xidsStringExample: user1,user2

APIEntitiesFeatureFlagScope

PropertyTypeDescription
environment_scopeStringExample: production
idInteger (int64)Example: 1

APIEntitiesFeatureFlagSettings

PropertyTypeDescription
minimum_roleStringExample: developer

APIEntitiesFeatureFlagStrategy

PropertyTypeDescription
idInteger (int64)Example: 1
nameStringExample: userWithId
parametersStringExample: {"userIds": "user1"}
scopesAPIEntitiesFeatureFlagScope—
user_listAPIEntitiesFeatureFlagBasicUserList—

APIEntitiesFeatureFlagUserList

PropertyTypeDescription
created_atString (date-time)Example: 2020-02-04T08:13:10.507Z
edit_pathString—
idInteger (int64)Example: 1
iidIntegerExample: 1
nameStringExample: user_list
pathString—
project_idInteger (int64)Example: 2
updated_atString (date-time)Example: 2020-02-04T08:13:10.507Z
user_xidsStringExample: user1,user2
←
REST API / External status checks
REST API / Features
→