Feature flags API

Version history

API for accessing resources of GitLab feature flags.

Users with at least the Developer role can access the feature flag API.

Feature flags pagination

By default, GET requests return 20 results at a time because the API results are paginated.

List feature flags for a project

Gets all feature flags of the requested project.

GET /projects/:id/feature_flags
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project.
scopestringnoThe condition of feature flags, one of: enabled, disabled.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags"

Example response:

[
   {
      "name":"merge_train",
      "description":"This feature is about merge train",
      "active": true,
      "version": "new_version_flag",
      "created_at":"2019-11-04T08:13:51.423Z",
      "updated_at":"2019-11-04T08:13:51.423Z",
      "scopes":[],
      "strategies": [
        {
          "id": 1,
          "name": "userWithId",
          "parameters": {
            "userIds": "user1"
          },
          "scopes": [
            {
              "id": 1,
              "environment_scope": "production"
            }
          ],
          "user_list": null
        }
      ]
   },
   {
      "name":"new_live_trace",
      "description":"This is a new live trace feature",
      "active": true,
      "version": "new_version_flag",
      "created_at":"2019-11-04T08:13:10.507Z",
      "updated_at":"2019-11-04T08:13:10.507Z",
      "scopes":[],
      "strategies": [
        {
          "id": 2,
          "name": "default",
          "parameters": {},
          "scopes": [
            {
              "id": 2,
              "environment_scope": "staging"
            }
          ],
          "user_list": null
        }
      ]
   },
   {
      "name":"user_list",
      "description":"This feature is about user list",
      "active": true,
      "version": "new_version_flag",
      "created_at":"2019-11-04T08:13:10.507Z",
      "updated_at":"2019-11-04T08:13:10.507Z",
      "scopes":[],
      "strategies": [
        {
          "id": 2,
          "name": "gitlabUserList",
          "parameters": {},
          "scopes": [
            {
              "id": 2,
              "environment_scope": "staging"
            }
          ],
          "user_list": {
            "id": 1,
            "iid": 1,
            "name": "My user list",
            "user_xids": "user1,user2,user3"
          }
        }
      ]
   }
]

Get a single feature flag

Gets a single feature flag.

GET /projects/:id/feature_flags/:feature_flag_name
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project.
feature_flag_namestringyesThe name of the feature flag.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature"

Example response:

{
  "name": "awesome_feature",
  "description": null,
  "active": true,
  "version": "new_version_flag",
  "created_at": "2020-05-13T19:56:33.119Z",
  "updated_at": "2020-05-13T19:56:33.119Z",
  "scopes": [],
  "strategies": [
    {
      "id": 36,
      "name": "default",
      "parameters": {},
      "scopes": [
        {
          "id": 37,
          "environment_scope": "production"
        }
      ],
      "user_list": null
    }
  ]
}

Create a feature flag

Creates a new feature flag.

POST /projects/:id/feature_flags
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project.
namestringyesThe name of the feature flag.
versionstringyesThe version of the feature flag. Must be new_version_flag. Omit to create a Legacy feature flag.
descriptionstringnoThe description of the feature flag.
activebooleannoThe active state of the flag. Defaults to true. Supported in GitLab 13.3 and later.
strategiesarray of strategy JSON objectsnoThe feature flag strategies.
strategies:nameJSONnoThe strategy name. Can be default, gradualRolloutUserId, userWithId, or gitlabUserList. In GitLab 13.5 and later, can be flexibleRollout.
strategies:parametersJSONnoThe strategy parameters.
strategies:scopesJSONnoThe scopes for the strategy.
strategies:scopes:environment_scopestringnoThe environment scope of the scope.
strategies:user_list_idinteger/stringnoThe ID of the feature flag user list. If strategy is gitlabUserList.
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-type: application/json" \
     --data @- << EOF
{
  "name": "awesome_feature",
  "version": "new_version_flag",
  "strategies": [{ "name": "default", "parameters": {}, "scopes": [{ "environment_scope": "production" }] }]
}
EOF

Example response:

{
  "name": "awesome_feature",
  "description": null,
  "active": true,
  "version": "new_version_flag",
  "created_at": "2020-05-13T19:56:33.119Z",
  "updated_at": "2020-05-13T19:56:33.119Z",
  "scopes": [],
  "strategies": [
    {
      "id": 36,
      "name": "default",
      "parameters": {},
      "scopes": [
        {
          "id": 37,
          "environment_scope": "production"
        }
      ]
    }
  ]
}

Update a feature flag

Updates a feature flag.

PUT /projects/:id/feature_flags/:feature_flag_name
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project.
feature_flag_namestringyesThe current name of the feature flag.
descriptionstringnoThe description of the feature flag.
activebooleannoThe active state of the flag. Supported in GitLab 13.3 and later.
namestringnoThe new name of the feature flag. Supported in GitLab 13.3 and later.
strategiesarray of strategy JSON objectsnoThe feature flag strategies.
strategies:idJSONnoThe feature flag strategy ID.
strategies:nameJSONnoThe strategy name.
strategies:_destroybooleannoDelete the strategy when true.
strategies:parametersJSONnoThe strategy parameters.
strategies:scopesJSONnoThe scopes for the strategy.
strategies:scopes:idJSONnoThe environment scope ID.
strategies:scopes:environment_scopestringnoThe environment scope of the scope.
strategies:scopes:_destroybooleannoDelete the scope when true.
strategies:user_list_idinteger/stringnoThe ID of the feature flag user list. If strategy is gitlabUserList.
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-type: application/json" \
     --data @- << EOF
{
  "strategies": [{ "name": "gradualRolloutUserId", "parameters": { "groupId": "default", "percentage": "25" }, "scopes": [{ "environment_scope": "staging" }] }]
}
EOF

Example response:

{
  "name": "awesome_feature",
  "description": null,
  "active": true,
  "version": "new_version_flag",
  "created_at": "2020-05-13T20:10:32.891Z",
  "updated_at": "2020-05-13T20:10:32.891Z",
  "scopes": [],
  "strategies": [
    {
      "id": 38,
      "name": "gradualRolloutUserId",
      "parameters": {
        "groupId": "default",
        "percentage": "25"
      },
      "scopes": [
        {
          "id": 40,
          "environment_scope": "staging"
        }
      ]
    },
    {
      "id": 37,
      "name": "default",
      "parameters": {},
      "scopes": [
        {
          "id": 39,
          "environment_scope": "production"
        }
      ]
    }
  ]
}

Delete a feature flag

Deletes a feature flag.

DELETE /projects/:id/feature_flags/:feature_flag_name
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project.
feature_flag_namestringyesThe name of the feature flag.
curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature"