2020-06-17 03:08:38 +00:00
---
stage: Release
2020-12-01 15:09:28 +00:00
group: Release
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-17 03:08:38 +00:00
---
2021-01-28 06:08:59 +00:00
# Legacy Feature Flags API **(FREE)**
2020-05-22 15:08:09 +00:00
2020-10-13 15:08:53 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.4.
2021-01-29 21:09:34 +00:00
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.5.
2020-05-22 15:08:09 +00:00
2020-12-04 21:09:29 +00:00
WARNING:
2020-05-22 15:08:09 +00:00
This API is deprecated and [scheduled for removal in GitLab 14.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/213369 ). Use [this API ](feature_flags.md ) instead.
2020-07-09 21:09:33 +00:00
API for accessing resources of [GitLab Feature Flags ](../operations/feature_flags.md ).
2020-05-22 15:08:09 +00:00
Users with Developer or higher [permissions ](../user/permissions.md ) can access Feature Flag API.
## Feature Flags pagination
By default, `GET` requests return 20 results at a time because the API results
are [paginated ](README.md#pagination ).
## List feature flags for a project
Gets all feature flags of the requested project.
```plaintext
GET /projects/:id/feature_flags
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
| `scope` | string | no | The condition of feature flags, one of: `enabled` , `disabled` . |
```shell
2020-12-08 09:09:41 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/feature_flags"
2020-05-22 15:08:09 +00:00
```
Example response:
```json
[
{
"name":"merge_train",
"description":"This feature is about merge train",
2020-08-03 09:09:42 +00:00
"active": true,
2020-05-22 15:08:09 +00:00
"created_at":"2019-11-04T08:13:51.423Z",
"updated_at":"2019-11-04T08:13:51.423Z",
"scopes":[
{
"id":82,
"active":false,
"environment_scope":"*",
"strategies":[
{
"name":"default",
"parameters":{
}
}
],
"created_at":"2019-11-04T08:13:51.425Z",
"updated_at":"2019-11-04T08:13:51.425Z"
},
{
"id":83,
"active":true,
"environment_scope":"review/*",
"strategies":[
{
"name":"default",
"parameters":{
}
}
],
"created_at":"2019-11-04T08:13:51.427Z",
"updated_at":"2019-11-04T08:13:51.427Z"
},
{
"id":84,
"active":false,
"environment_scope":"production",
"strategies":[
{
"name":"default",
"parameters":{
}
}
],
"created_at":"2019-11-04T08:13:51.428Z",
"updated_at":"2019-11-04T08:13:51.428Z"
}
]
},
{
"name":"new_live_trace",
"description":"This is a new live trace feature",
2020-08-03 09:09:42 +00:00
"active": true,
2020-05-22 15:08:09 +00:00
"created_at":"2019-11-04T08:13:10.507Z",
"updated_at":"2019-11-04T08:13:10.507Z",
"scopes":[
{
"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
Creates a new feature flag.
```plaintext
POST /projects/:id/feature_flags
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
| `name` | string | yes | The name of the feature flag. |
| `description` | string | no | The description of the feature flag. |
2020-08-03 09:09:42 +00:00
| `active` | boolean | no | The active state of the flag. Defaults to true. [Supported ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350 ) in GitLab 13.3 and later. |
2020-05-22 15:08:09 +00:00
| `scopes` | JSON | no | The feature flag specs of the feature flag. |
| `scopes:environment_scope` | string | no | The environment spec. |
| `scopes:active` | boolean | no | Whether the spec is active. |
2020-07-09 21:09:33 +00:00
| `scopes:strategies` | JSON | no | The [strategies ](../operations/feature_flags.md#feature-flag-strategies ) of the feature flag spec. |
2020-05-22 15:08:09 +00:00
```shell
2020-12-08 09:09:41 +00:00
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags" \
2020-05-22 15:08:09 +00:00
--header "PRIVATE-TOKEN: < your_access_token > " \
--header "Content-type: application/json" \
--data @- < < EOF
{
"name": "awesome_feature",
"scopes": [{ "environment_scope": "*", "active": false, "strategies": [{ "name": "default", "parameters": {} }] },
{ "environment_scope": "production", "active": true, "strategies": [{ "name": "userWithId", "parameters": { "userIds": "1,2,3" } }] }]
}
EOF
```
Example response:
```json
{
"name":"awesome_feature",
"description":null,
2020-08-03 09:09:42 +00:00
"active": true,
2020-05-22 15:08:09 +00:00
"created_at":"2019-11-04T08:32:27.288Z",
"updated_at":"2019-11-04T08:32:27.288Z",
"scopes":[
{
"id":85,
"active":false,
"environment_scope":"*",
"strategies":[
{
"name":"default",
"parameters":{
}
}
],
"created_at":"2019-11-04T08:32:29.324Z",
"updated_at":"2019-11-04T08:32:29.324Z"
},
{
"id":86,
"active":true,
"environment_scope":"production",
"strategies":[
{
"name":"userWithId",
"parameters":{
"userIds":"1,2,3"
}
}
],
"created_at":"2019-11-04T08:32:29.328Z",
"updated_at":"2019-11-04T08:32:29.328Z"
}
]
}
```
## Single feature flag
Gets a single feature flag.
```plaintext
GET /projects/:id/feature_flags/:name
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
| `name` | string | yes | The name of the feature flag. |
```shell
2020-12-08 09:09:41 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace"
2020-05-22 15:08:09 +00:00
```
Example response:
```json
{
"name":"new_live_trace",
"description":"This is a new live trace feature",
2020-08-03 09:09:42 +00:00
"active": true,
2020-05-22 15:08:09 +00:00
"created_at":"2019-11-04T08:13:10.507Z",
"updated_at":"2019-11-04T08:13:10.507Z",
"scopes":[
{
"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"
}
]
}
```
## Delete feature flag
Deletes a feature flag.
```plaintext
DELETE /projects/:id/feature_flags/:name
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
| `name` | string | yes | The name of the feature flag. |
```shell
2020-12-08 09:09:41 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " --request DELETE "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature"
2020-05-22 15:08:09 +00:00
```