Manage flags
11 min
Manage flags using the Feature Experimentation REST API
See the Feature Experimentation API referenceFeature Experimentation API reference for information on using the flags endpoints.
<Add_API_Key />
Create a flag
See the Create feature flagsCreate feature flags documentation for information.
Read all flags
Use the List FlagsList Flags API endpoint.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags
Example request
curl --request GET \
--url 'https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags' \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Example response
{
"page": 1,
"fetch_flag_url": "/projects/PROJECT_ID/flags/{flag_key}",
"total_pages": 1,
"first_url": "/projects/PROJECT_ID/flags",
"count": 3,
"last_url": "/projects/PROJECT_ID/flags",
"url": "/projects/PROJECT_ID/flags",
"items": [
{
"key": "doc-test-flag",
"name": "Doc test flag",
"description": "Flag created through the API",
"url": "/projects/PROJECT_ID/flags/doc-test-flag",
"update_url": "/projects/PROJECT_ID/flags",
"delete_url": "/projects/PROJECT_ID/flags/doc-test-flag",
"archive_url": "/projects/PROJECT_ID/flags/archived",
"variable_definitions": {
"show_amounts": {
"key": "show_amounts",
"description": "If inventory is shown, this variable controls what is displayed: available/unavailable vs the actual inventory amount.",
"type": "boolean",
"default_value": "false",
"created_time": "2025-09-12T16:23:14.258485Z",
"updated_time": "2025-09-12T16:23:14.258487Z"
}
},
"environments": {
"production": {
"key": "production",
"name": "Production",
"enabled": false,
"has_restricted_permissions": true,
"priority": 1,
"status": "draft",
"rules_summary": {},
"rules_detail": [],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/doc-test-flag/environments/production/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
},
"development": {
"key": "development",
"name": "Development",
"enabled": false,
"has_restricted_permissions": false,
"priority": 2,
"status": "draft",
"rules_summary": {
"a/b": {
"keys": [
"already-existing-a-b-test"
]
},
"multi_armed_bandit": {
"keys": [
"mab_test"
]
}
},
"rules_detail": [
{
"updated_time": "2025-09-12T17:03:20.001335Z",
"id": ID,
"layer_experiment_id": LAYER_EXPERIMENT_ID,
"key": "already-existing-a-b-test",
"audience_ids": [
AUDIENCE_ID
],
"primary_metric": "PDP Page Views",
"variation_names": [
"Off",
"On"
],
"status": "draft",
"days_running": null,
"distribution_mode": "manual",
"type": "a/b",
"fetch_results_ui_url": null,
"created_time": "2025-09-12T16:44:11.824135Z",
"traffic_allocation": 10000,
"created_by_user_email": "[email protected]",
"enabled": false,
"name": "Already-existing-a-b-test"
}
],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/doc-test-flag/environments/development/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
}
},
"id": ID,
"urn": "flags.flags.optimizely.com::ID",
"archived": false,
"outlier_filtering_enabled": true,
"project_id": PROJECT_ID,
"created_by_user_id": "[email protected]",
"created_by_user_email": "[email protected]",
"account_id": ACCOUNT_ID,
"role": "admin",
"created_time": "2025-09-12T16:16:10.260857Z",
"updated_time": "2025-09-12T17:45:10.487636Z",
"revision": 1
},
{
"key": "homepage_hero",
"name": "Homepage hero",
"description": "",
"url": "/projects/PROJECT_ID/flags/homepage_hero",
"update_url": "/projects/PROJECT_ID/flags",
"delete_url": "/projects/PROJECT_ID/flags/homepage_hero",
"archive_url": "/projects/PROJECT_ID/flags/archived",
"variable_definitions": {},
"environments": {
"production": {
"key": "production",
"name": "Production",
"enabled": false,
"has_restricted_permissions": true,
"priority": 1,
"status": "draft",
"rules_summary": {},
"rules_detail": [],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/homepage_hero/environments/production/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
},
"development": {
"key": "development",
"name": "Development",
"enabled": false,
"has_restricted_permissions": false,
"priority": 2,
"status": "draft",
"rules_summary": {},
"rules_detail": [],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/homepage_hero/environments/development/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
}
},
"id": ID,
"urn": "flags.flags.optimizely.com::ID",
"archived": false,
"outlier_filtering_enabled": false,
"project_id": PROJECT_ID,
"created_by_user_id": "[email protected]",
"created_by_user_email": "[email protected]",
"account_id": ACCOUNT_ID,
"role": "admin",
"created_time": "2025-05-22T08:56:42.894695Z",
"updated_time": "2025-05-22T09:01:47.500000Z",
"revision": 1
},
{
"key": "product_sort",
"name": "Product sort",
"description": "",
"url": "/projects/PROJECT_ID/flags/product_sort",
"update_url": "/projects/PROJECT_ID/flags",
"delete_url": "/projects/PROJECT_ID/flags/product_sort",
"archive_url": "/projects/PROJECT_ID/flags/archived",
"variable_definitions": {
"display_sort_algorithm": {
"key": "display_sort_algorithm",
"description": "Whether to display the sorting algorithm to the user.",
"type": "boolean",
"default_value": "true",
"created_time": "2025-04-14T21:47:46.837014Z",
"updated_time": "2025-04-14T21:47:46.837014Z"
},
"sort_algorithm": {
"key": "sort_algorithm",
"description": "The name of the sorting algorithm to be tested.",
"type": "string",
"default_value": "our popular first",
"created_time": "2025-04-14T21:47:46.837014Z",
"updated_time": "2025-04-14T21:47:46.837015Z"
},
"sort_algorithm_position": {
"key": "sort_algorithm_position",
"description": "The position of the sorting algorithm in the list of sorting algorithms.",
"type": "integer",
"default_value": "1",
"created_time": "2025-04-14T21:47:46.837011Z",
"updated_time": "2025-04-14T21:47:46.837013Z"
},
"sort_method": {
"key": "sort_method",
"description": "",
"type": "string",
"default_value": "alphabetical",
"created_time": "2025-04-29T20:53:37.811287Z",
"updated_time": "2025-04-29T20:53:37.811292Z"
}
},
"environments": {
"production": {
"key": "production",
"name": "Production",
"enabled": true,
"has_restricted_permissions": true,
"priority": 1,
"status": "running",
"rules_summary": {
"a/b": {
"keys": [
"experiment"
]
}
},
"rules_detail": [
{
"updated_time": "2025-04-29T21:10:26.370340Z",
"id": ID,
"layer_experiment_id": LAYER_EXPERIMENT_ID,
"key": "experiment",
"audience_ids": [],
"primary_metric": "purchase",
"variation_names": [
"Off",
"On"
],
"status": "running",
"days_running": 135,
"distribution_mode": "manual",
"type": "a/b",
"fetch_results_ui_url": "https://app.optimizely.com/v2/projects/PROJECT_ID/results/RESULTS_ID/experiments/EXPERIMENT_ID",
"created_time": "2025-04-29T21:10:01.059880Z",
"traffic_allocation": 10000,
"created_by_user_email": "[email protected]",
"enabled": true,
"name": "experiment"
}
],
"id": ID,
"disable_url": "/projects/PROJECT_ID/flags/product_sort/environments/production/ruleset/disabled",
"created_time": "2025-04-14T19:48:26.000000Z"
},
"development": {
"key": "development",
"name": "Development",
"enabled": false,
"has_restricted_permissions": false,
"priority": 2,
"status": "draft",
"rules_summary": {
"a/b": {
"keys": [
"best_sort_method"
]
}
},
"rules_detail": [
{
"updated_time": "2025-04-14T21:49:39.008847Z",
"id": ID,
"layer_experiment_id": LAYER_EXPERIMENT_ID,
"key": "best_sort_method",
"audience_ids": [],
"primary_metric": "Cross-project-metric",
"variation_names": [
"Off"
],
"status": "draft",
"days_running": null,
"distribution_mode": "manual",
"type": "a/b",
"fetch_results_ui_url": null,
"created_time": "2025-04-14T21:44:42.781693Z",
"traffic_allocation": 10000,
"created_by_user_email": "[email protected]",
"enabled": false,
"name": "Best sort method"
}
],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/product_sort/environments/development/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
}
},
"id": ID,
"urn": "flags.flags.optimizely.com::ID",
"archived": false,
"outlier_filtering_enabled": false,
"project_id": PROJECT_ID,
"created_by_user_id": "[email protected]",
"created_by_user_email": "[email protected]",
"account_id": ACCOUNT_ID,
"role": "admin",
"created_time": "2025-04-14T19:54:57.618260Z",
"updated_time": "2025-04-29T21:10:23.587597Z",
"revision": 3
}
],
"total_count": 3,
"create_url": "/projects/PROJECT_ID/flags"
}See the List FlagsList Flags endpoint reference documentation for information on the optional query parameters.
Read a single flag
Use the Fetch a Single FlagFetch a Single Flag API endpoint to list a flag's details.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY
Example request
curl --request GET \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Example response
{
"key": "doc-test-flag",
"name": "Doc test flag",
"description": "Flag created through the API",
"url": "/projects/PROJECT_ID/flags/doc-test-flag",
"update_url": "/projects/PROJECT_ID/flags",
"delete_url": "/projects/PROJECT_ID/flags/doc-test-flag",
"archive_url": "/projects/PROJECT_ID/flags/archived",
"variable_definitions": {
"show_amounts": {
"key": "show_amounts",
"description": "If inventory is shown, this variable controls what is displayed: available/unavailable vs the actual inventory amount.",
"type": "boolean",
"default_value": "false",
"created_time": "2025-09-12T16:23:14.258485Z",
"updated_time": "2025-09-12T16:23:14.258487Z"
}
},
"environments": {
"production": {
"key": "production",
"name": "Production",
"enabled": false,
"has_restricted_permissions": true,
"priority": 1,
"status": "draft",
"rules_summary": {},
"rules_detail": [],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/doc-test-flag/environments/production/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
},
"development": {
"key": "development",
"name": "Development",
"enabled": false,
"has_restricted_permissions": false,
"priority": 2,
"status": "draft",
"rules_summary": {
"a/b": {
"keys": [
"already-existing-a-b-test"
]
},
"multi_armed_bandit": {
"keys": [
"mab_test"
]
}
},
"rules_detail": [
{
"audience_ids": [
AUDIENCE_ID
],
"traffic_allocation": 10000,
"name": "Already-existing-a-b-test",
"variation_names": [
"Off",
"On"
],
"created_by_user_email": "[email protected]",
"layer_experiment_id": LAYER_EXPERIMENT_ID,
"primary_metric": "PDP Page Views",
"id": ID,
"key": "already-existing-a-b-test",
"distribution_mode": "manual",
"type": "a/b",
"updated_time": "2025-09-12T17:03:20.001335Z",
"status": "draft",
"fetch_results_ui_url": null,
"days_running": null,
"enabled": false,
"created_time": "2025-09-12T16:44:11.824135Z"
}
],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/doc-test-flag/environments/development/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
}
},
"id": ID,
"urn": "flags.flags.optimizely.com::ID",
"archived": false,
"outlier_filtering_enabled": true,
"project_id": PROJECT_ID,
"created_by_user_id": "[email protected]",
"created_by_user_email": "[email protected]",
"account_id": ACCOUNT_ID,
"role": "admin",
"created_time": "2025-09-12T16:16:10.260857Z",
"updated_time": "2025-09-12T17:45:10.487636Z",
"revision": 1
}Update a flag
Use the Update FlagsUpdate Flags API endpoint.
Important For PATCH requests, first read the flag, merge only the fields you need to change, and then send the PATCH. This helps prevent overwriting existing settings you did not intend to modify.
Endpoint – PATCH https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags
Example request
curl --request PATCH \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN' \
--header 'content-type: application/json-patch+json' \
--data '
[
{
"op": "replace",
"path": "/FLAG_KEY/description",
"value": "Flag created with the API."
}
]
'Example response
{
"doc-test-flag": {
"key": "doc-test-flag",
"name": "Doc test flag",
"description": "Flag created with the API.",
"url": "/projects/PROJECT_ID/flags/doc-test-flag",
"update_url": "/projects/PROJECT_ID/flags",
"delete_url": "/projects/PROJECT_ID/flags/doc-test-flag",
"archive_url": "/projects/PROJECT_ID/flags/archived",
"variable_definitions": {
"show_amounts": {
"key": "show_amounts",
"description": "If inventory is shown, this variable controls what is displayed: available/unavailable vs the actual inventory amount.",
"type": "boolean",
"default_value": "false",
"created_time": "2025-09-12T16:23:14.258485Z",
"updated_time": "2025-09-12T16:23:14.258487Z"
}
},
"environments": {
"production": {
"key": "production",
"name": "Production",
"enabled": false,
"has_restricted_permissions": true,
"priority": 1,
"status": "draft",
"rules_summary": {},
"rules_detail": [],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/doc-test-flag/environments/production/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
},
"development": {
"key": "development",
"name": "Development",
"enabled": false,
"has_restricted_permissions": false,
"priority": 2,
"status": "draft",
"rules_summary": {
"a/b": {
"keys": [
"already-existing-a-b-test"
]
},
"multi_armed_bandit": {
"keys": [
"mab_test"
]
}
},
"rules_detail": [
{
"distribution_mode": "manual",
"status": "draft",
"enabled": false,
"fetch_results_ui_url": null,
"name": "Already-existing-a-b-test",
"created_time": "2025-09-12T16:44:11.824135Z",
"days_running": null,
"key": "already-existing-a-b-test",
"updated_time": "2025-09-12T17:03:20.001335Z",
"id": ID,
"traffic_allocation": 10000,
"primary_metric": "PDP Page Views",
"created_by_user_email": "[email protected]",
"audience_ids": [
AUDIENCE_ID
],
"type": "a/b",
"variation_names": [
"Off",
"On"
],
"layer_experiment_id": LAYER_EXPERIMENT_ID
}
],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/doc-test-flag/environments/development/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
}
},
"id": ID,
"urn": "flags.flags.optimizely.com::ID",
"archived": false,
"outlier_filtering_enabled": true,
"project_id": PROJECT_ID,
"created_by_user_id": "[email protected]",
"created_by_user_email": "[email protected]",
"account_id": ACCOUNT_ID,
"role": "admin",
"created_time": "2025-09-12T16:16:10.260857Z",
"updated_time": "2025-09-12T18:58:23.052921Z",
"revision": 2
}
}See the Update FlagsUpdate Flags endpoint reference documentation for information.
Archive a flag
Use Archive FlagsArchive Flags.
Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/archived
Example request
curl --request POST \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/archived \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN' \
--header 'content-type: application/json' \
--data '
{
"keys": [
"homepage_hero"
]
}
'Example response
{
"homepage_hero": {
"key": "homepage_hero",
"name": "Homepage hero",
"description": "",
"url": "/projects/PROJECT_ID/flags/homepage_hero",
"delete_url": "/projects/PROJECT_ID/flags/homepage_hero",
"unarchive_url": "/projects/PROJECT_ID/flags/unarchived",
"variable_definitions": {},
"environments": {
"production": {
"key": "production",
"name": "Production",
"enabled": false,
"has_restricted_permissions": true,
"priority": 1,
"status": "draft",
"rules_summary": {},
"rules_detail": [],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/homepage_hero/environments/production/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
},
"development": {
"key": "development",
"name": "Development",
"enabled": false,
"has_restricted_permissions": false,
"priority": 2,
"status": "draft",
"rules_summary": {},
"rules_detail": [],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/homepage_hero/environments/development/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
}
},
"id": ID,
"urn": "flags.flags.optimizely.com::ID",
"archived": true,
"outlier_filtering_enabled": false,
"project_id": PROJECT_ID,
"created_by_user_id": "[email protected]",
"created_by_user_email": "[email protected]",
"account_id": ACCOUNT_ID,
"role": "admin",
"created_time": "2025-05-22T08:56:42.894695Z",
"updated_time": "2025-09-12T19:08:18.387672Z",
"revision": 2
}
}Unarchive a flag
Use the Unarchive FlagsUnarchive Flags API endpoint.
Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/unarchived
Example request
curl --request POST \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/unarchived \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN' \
--header 'content-type: application/json' \
--data '
{
"keys": [
"homepage_hero"
]
}
'Example response
{
"homepage_hero": {
"key": "homepage_hero",
"name": "Homepage hero",
"description": "",
"url": "/projects/PROJECT_ID/flags/homepage_hero",
"update_url": "/projects/PROJECT_ID/flags",
"delete_url": "/projects/PROJECT_ID/flags/homepage_hero",
"archive_url": "/projects/PROJECT_ID/flags/archived",
"variable_definitions": {},
"environments": {
"production": {
"key": "production",
"name": "Production",
"enabled": false,
"has_restricted_permissions": true,
"priority": 1,
"status": "draft",
"rules_summary": {},
"rules_detail": [],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/homepage_hero/environments/production/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
},
"development": {
"key": "development",
"name": "Development",
"enabled": false,
"has_restricted_permissions": false,
"priority": 2,
"status": "draft",
"rules_summary": {},
"rules_detail": [],
"id": ID,
"enable_url": "/projects/PROJECT_ID/flags/homepage_hero/environments/development/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
}
},
"id": ID,
"urn": "flags.flags.optimizely.com::ID",
"archived": false,
"outlier_filtering_enabled": false,
"project_id": PROJECT_ID,
"created_by_user_id": "[email protected]",
"created_by_user_email": "[email protected]",
"account_id": ACCOUNT_ID,
"role": "admin",
"created_time": "2025-05-22T08:56:42.894695Z",
"updated_time": "2025-09-12T19:11:14.801763Z",
"revision": 3
}
}Delete a flag
Use the Delete a FlagDelete a Flag API endpoint.
Endpoint – DELETE https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY
Example request
curl --request DELETE \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Example response
The endpoint returns no content if successful.
Manage flags in the Feature Experimentation UI
See Manage flagsManage flags in the user documentation for information on managing flags, including how to create, pause, and update your flags.