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
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project.
scope string no The 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
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project.
feature_flag_name string yes The 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
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project.
name string yes The name of the feature flag.
version string yes The version of the feature flag. Must be new_version_flag. Omit to create a Legacy feature flag.
description string no The description of the feature flag.
active boolean no The active state of the flag. Defaults to true. Supported in GitLab 13.3 and later.
strategies array of strategy JSON objects no The feature flag strategies.
strategies:name JSON no The strategy name. Can be default, gradualRolloutUserId, userWithId, or gitlabUserList. In GitLab 13.5 and later, can be flexibleRollout.
strategies:parameters JSON no The strategy parameters.
strategies:scopes JSON no The scopes for the strategy.
strategies:scopes:environment_scope string no The environment scope of the scope.
strategies:user_list_id integer/string no The 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
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project.
feature_flag_name string yes The current name of the feature flag.
description string no The description of the feature flag.
active boolean no The active state of the flag. Supported in GitLab 13.3 and later.
name string no The new name of the feature flag. Supported in GitLab 13.3 and later.
strategies array of strategy JSON objects no The feature flag strategies.
strategies:id JSON no The feature flag strategy ID.
strategies:name JSON no The strategy name.
strategies:_destroy boolean no Delete the strategy when true.
strategies:parameters JSON no The strategy parameters.
strategies:scopes JSON no The scopes for the strategy.
strategies:scopes:id JSON no The environment scope ID.
strategies:scopes:environment_scope string no The environment scope of the scope.
strategies:scopes:_destroy boolean no Delete the scope when true.
strategies:user_list_id integer/string no The 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
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project.
feature_flag_name string yes The 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"