Manage flags
Information on how to manage flags in Optimizely Feature Experimentation.
Manage flags using the Feature Experimentation REST API
See the Optimizely Feature Experimentation API reference for information on using the flags endpoints.
For each cURL command, include your API key in the Authorization header as a Bearer token. See Generate tokens and use the REST APIs for information.
Create a flag
See the Create feature flags documentation for information.
Read all flags
Use the List Flags API endpoint.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags
Request example
curl --request GET \
--url 'https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags' \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Response example
{
"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-exisiting-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-exisiting-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-exisiting-a-b-test"
}
],
"id": 761744660106841,
"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": "user2optimizely.com",
"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": 1291104,
"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/ENVIRONMENT-ID/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 Flags endpoint reference documentation for information on the optional query parameters.
Read a single flag
Use the Fetch 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
Request example
curl --request GET \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Response example
{
"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-exisiting-a-b-test"
]
},
"multi_armed_bandit": {
"keys": [
"mab_test"
]
}
},
"rules_detail": [
{
"audience_ids": [
AUDIENCE_ID
],
"traffic_allocation": 10000,
"name": "Already-exisiting-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-exisiting-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 Flags API endpoint.
ImportantFor
PATCHrequests, first fetch a flag, merge only the fields you need to change, and then send thePATCH. This helps prevent overwriting existing settings you did not intend to modify.
Endpoint – PATCH https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags
Request example
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."
}
]
'Response example
{
"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-exisiting-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-exisiting-a-b-test",
"created_time": "2025-09-12T16:44:11.824135Z",
"days_running": null,
"key": "already-exisiting-a-b-test",
"updated_time": "2025-09-12T17:03:20.001335Z",
"id": 1598646,
"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 Flags endpoint reference documentation for information.
Archive a flag
Use Archive Flags.
Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/archived
Request example
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"
]
}
'Response example
{
"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 Flags API endpoint.
Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/unarchived
Request example
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"
]
}
'Response example
{
"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": 419948,
"urn": "flags.flags.optimizely.com::419948",
"archived": false,
"outlier_filtering_enabled": false,
"project_id": 5629661695180800,
"created_by_user_id": "[email protected]",
"created_by_user_email": "[email protected]",
"account_id": 10886221501,
"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 Flag API endpoint.
Endpoint – DELETE https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY
Request example
curl --request DELETE \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/homepage_hero \
--header 'accept: application/problem+json' \
--header 'authorization: Bearer TOKEN'Response example
The endpoint returns no content if successful.
Manage flags in the Feature Experimentation UI
See Manage flags in the user documentation for information on managing flags, including how to create, pause, and update your flags.
Updated 8 days ago