--- title: Manage flags slug: feature-experimentation/docs/manage-flags docTags: createdAt: 2026-08-05T20:39:58.000Z --- ## Manage flags using the Feature Experimentation REST API See the [Feature Experimentation API reference](docId\:J6jMGAvkqAepvYM-hZlAk) for information on using the `flags` endpoints. \ ### Create a flag See the [Create feature flags](docId\:Z0Yy8O0N7GakXKfCPYtSi) documentation for information. ### Read all flags Use the [List Flags](docId\:J6jMGAvkqAepvYM-hZlAk) API endpoint. **Endpoint** – `GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags` **Example request** ```curl curl --request GET \ --url 'https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags' \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN' ``` **Example response** ```json { "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": "user@optimizely.com", "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": "user@optimizely.com", "created_by_user_email": "user@optimizely.com", "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": "user2@optimizely.com", "created_by_user_email": "user2@optimizely.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": "user@optimizely.com", "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": "user@optimizely.com", "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": "user@optimizely.com", "created_by_user_email": "user@optimizely.com", "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](docId\:J6jMGAvkqAepvYM-hZlAk) endpoint reference documentation for information on the optional query parameters. ### Read a single flag Use the [Fetch a Single Flag](docId\:QQwFMyG-lCVfz3rmdv4aS) 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 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** ```json { "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": "user@optimizely.com", "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": "user@optimizely.com", "created_by_user_email": "user@optimizely.com", "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](docId\:wqy7sJmBoPO-8gwvdhvVC) API endpoint. :::hint{type="warning"} **Important** For `PATCH` requests, first [read the flag](docId\:XAKiLcqOwEMEHt923sCS2), 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 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** ```json { "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": "user@optimizely.com", "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": "user@optimizely.com", "created_by_user_email": "user@optimizely.com", "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](docId\:wqy7sJmBoPO-8gwvdhvVC) endpoint reference documentation for information. ### Archive a flag Use [Archive Flags](docId\:IndrKVFuNJ3BZQQulUCJC). **Endpoint** – `POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/archived` **Example request** ```curl 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** ```json { "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": "user@optimizely.com", "created_by_user_email": "user@optimizely.com", "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](docId\:Lymq0RXol61GlMUYt7WO6) API endpoint. **Endpoint** – `POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/unarchived` **Example request** ```curl 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** ```json { "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": "user@optimizely.com", "created_by_user_email": "user@optimizely.com", "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 Flag](docId\:gBaL0jSsjn4t4QkqSNq32) API endpoint. **Endpoint** – `DELETE https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY` **Example request** ```curl 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 flags](docId\:j7bgkTxrI8VN_z2dOZu1R) in the user documentation for information on managing flags, including how to create, pause, and update your flags.