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 integerThe ID or URL-encoded path of the project
scope
Query		StringThe scope of feature flags, one of: enabled, disabled
Allowed values: enabled, disabled
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureFlag
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 integerThe ID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
activeBooleanThe active state of the flag. Defaults to true. Supported in GitLab 13.3 and later
descriptionStringThe description of the feature flag
name
Required		StringThe name of the feature flag
strategiesArray of objectsArray of feature flag strategies
strategies[].name
Required		StringThe strategy name. Can be default, gradualRolloutUserId, userWithId, or gitlabUserList. In GitLab 13.5 and later, can be flexibleRollout
strategies[].parametersObjectThe strategy parameters as a JSON-formatted string e.g. {"userIds":"user1"}
strategies[].scopesArray of objectsArray of scopes for the strategy
strategies[].scopes[].environment_scope
Required		StringThe environment scope of the scope
strategies[].user_list_idIntegerThe ID of the feature flag user list. If 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 integerThe ID or URL-encoded path of the project
feature_flag_name
Path, required		StringThe name 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 integerThe ID or URL-encoded path of the project
feature_flag_name
Path, required		StringThe name of the feature flag

Request body (application/json)

PropertyTypeDescription
activeBooleanThe active state of the flag. Supported in GitLab 13.3 and later
descriptionStringThe description of the feature flag
nameStringThe new name of the feature flag. Supported in GitLab 13.3 and later
strategiesArray of objectsArray of feature flag strategies
strategies[]._destroyBooleanDelete the strategy when true
strategies[].idIntegerThe feature flag strategy ID
strategies[].nameStringThe strategy name
strategies[].parametersObjectThe strategy parameters as a JSON-formatted string e.g. {"userIds":"user1"}
strategies[].scopesArray of objectsArray of scopes for the strategy
strategies[].scopes[]._destroyBooleanDelete the scope when true
strategies[].scopes[].environment_scopeStringThe environment scope of the scope
strategies[].scopes[].idIntegerThe scope id
strategies[].user_list_idIntegerThe ID of the feature flag user list

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 integerThe ID or URL-encoded path of the project
feature_flag_name
Path, required		StringThe name 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 integerThe ID 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 integerThe ID 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		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureFlagUserList
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
→