Feature Flag Specs API (PREMIUM)

Introduced in GitLab Premium 12.5.

The API for creating, updating, reading and deleting Feature Flag Specs. Automation engineers benefit from this API by being able to modify Feature Flag Specs without accessing user interface. To manage the Feature Flag resources via public API, please refer to the Feature Flags API document.

Users with Developer or higher permissions can access Feature Flag Specs API.

List all effective feature flag specs under the specified environment

Get all effective feature flag specs under the specified environment.

For instance, there are two specs, staging and production, for a feature flag. When you pass production as a parameter to this endpoint, the system returns the production feature flag spec only.

GET /projects/:id/feature_flag_scopes

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project.
environment	string	yes	The environment name

curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/feature_flag_scopes?environment=production

Example response:

[
  {
    "id": 88,
    "active": true,
    "environment_scope": "production",
    "strategies": [
      {
        "name": "userWithId",
        "parameters": {
          "userIds": "1,2,3"
        }
      }
    ],
    "created_at": "2019-11-04T08:36:41.327Z",
    "updated_at": "2019-11-04T08:36:41.327Z",
    "name": "awesome_feature"
  },
  {
    "id": 82,
    "active": true,
    "environment_scope": "*",
    "strategies": [
      {
        "name": "default",
        "parameters": {}
      }
    ],
    "created_at": "2019-11-04T08:13:51.425Z",
    "updated_at": "2019-11-04T08:39:45.751Z",
    "name": "merge_train"
  },
  {
    "id": 81,
    "active": false,
    "environment_scope": "production",
    "strategies": [
      {
        "name": "default",
        "parameters": {}
      }
    ],
    "created_at": "2019-11-04T08:13:10.527Z",
    "updated_at": "2019-11-04T08:13:10.527Z",
    "name": "new_live_trace"
  }
]

List all specs of a feature flag

Get all specs of a feature flag.

GET /projects/:id/feature_flags/:name/scopes

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.

curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes

Example response:

[
  {
    "id": 79,
    "active": false,
    "environment_scope": "*",
    "strategies": [
      {
        "name": "default",
        "parameters": {}
      }
    ],
    "created_at": "2019-11-04T08:13:10.516Z",
    "updated_at": "2019-11-04T08:13:10.516Z"
  },
  {
    "id": 80,
    "active": true,
    "environment_scope": "staging",
    "strategies": [
      {
        "name": "default",
        "parameters": {}
      }
    ],
    "created_at": "2019-11-04T08:13:10.525Z",
    "updated_at": "2019-11-04T08:13:10.525Z"
  },
  {
    "id": 81,
    "active": false,
    "environment_scope": "production",
    "strategies": [
      {
        "name": "default",
        "parameters": {}
      }
    ],
    "created_at": "2019-11-04T08:13:10.527Z",
    "updated_at": "2019-11-04T08:13:10.527Z"
  }
]

New feature flag spec

Creates a new feature flag spec.

POST /projects/:id/feature_flags/:name/scopes

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.
environment_scope	string	yes	The environment spec of the feature flag.
active	boolean	yes	Whether the spec is active.
strategies	json	yes	The strategies of the feature flag spec.

curl https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-type: application/json" \
     --data @- << EOF
{
    "environment_scope": "*",
    "active": false,
    "strategies": [{ "name": "default", "parameters": {} }]
}
EOF

Example response:

{
  "id": 81,
  "active": false,
  "environment_scope": "*",
  "strategies": [
    {
      "name": "default",
      "parameters": {}
    }
  ],
  "created_at": "2019-11-04T08:13:10.527Z",
  "updated_at": "2019-11-04T08:13:10.527Z"
}

Single feature flag spec

Gets a single feature flag spec.

GET /projects/:id/feature_flags/:name/scopes/:environment_scope

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.
environment_scope	string	yes	The URL-encoded environment spec of the feature flag.

curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/feature_flags/new_live_trace/scopes/production

Example response:

{
  "id": 81,
  "active": false,
  "environment_scope": "production",
  "strategies": [
    {
      "name": "default",
      "parameters": {}
    }
  ],
  "created_at": "2019-11-04T08:13:10.527Z",
  "updated_at": "2019-11-04T08:13:10.527Z"
}

Edit feature flag spec

Updates an existing feature flag spec.

PUT /projects/:id/feature_flags/:name/scopes/:environment_scope

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.
environment_scope	string	yes	The URL-encoded environment spec of the feature flag.
active	boolean	yes	Whether the spec is active.
strategies	json	yes	The strategies of the feature flag spec.

curl https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes/production \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-type: application/json" \
     --data @- << EOF
{
    "active": true,
    "strategies": [{ "name": "userWithId", "parameters": { "userIds": "1,2,3" } }]
}
EOF

Example response:

{
  "id": 81,
  "active": true,
  "environment_scope": "production",
  "strategies": [
    {
      "name": "userWithId",
      "parameters": { "userIds": "1,2,3" }
    }
  ],
  "created_at": "2019-11-04T08:13:10.527Z",
  "updated_at": "2019-11-04T08:13:10.527Z"
}

Delete feature flag spec

Deletes a feature flag spec.

DELETE /projects/:id/feature_flags/:name/scopes/:environment_scope

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.
environment_scope	string	yes	The URL-encoded environment spec of the feature flag.

curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes/production