--- title: Manage rules slug: feature-experimentation/docs/manage-rules docTags: createdAt: 2026-08-05T20:39:59.000Z --- Rules contain the experiment and targeting logic within a flag. Rules describe what variation the flag should deliver to a given user. A ruleset is the collection of rules associated with a flag. ## With the Feature Experimentation REST API See the [Rulesets](docId\:TxxX0KcGkrO_cG331nADs) and [Rules](docId\:YYvzC4lOorCtWiVhPKMmL) API endpoints for information on managing rules with the Feature Experimentation REST API. For each cURL command, include your API key in the `Authorization` header as a Bearer token. See [Generate tokens and use the REST APIs](docId\:pQfa5KPTbmy6crey-nsrd) for information. ## Rulesets ### Read rulesets Use the [Fetch the Ruleset for a Flag in an Environment](docId\:TxxX0KcGkrO_cG331nADs) API endpoint. **Endpoint** – `GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset` **Example request** ```curl curl --request GET \ --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN' ``` **Example response** ```json { "url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset", "update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset", "disable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/disabled", "rules": { "landing_page_targeted_delivery": { "key": "landing_page_targeted_delivery", "name": "Targeted Delivery for the landing page", "description": "", "variations": { "on": { "key": "on", "name": "On", "percentage_included": 10000, "variation_id": 1500954, "id": 6669615 } }, "baseline_variation_id": null, "type": "targeted_delivery", "id": 1598837, "urn": "rules.flags.optimizely.com::1598837", "archived": false, "enabled": true, "created_time": "2025-09-12T20:14:49.374112Z", "updated_time": "2025-09-12T20:39:18.170572Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [], "allow_list": {}, "layer_id": 9300001985290, "layer_experiment_id": 9300002731002, "status": "running" } }, "rule_priorities": [], "id": 1881462, "urn": "rulesets.flags.optimizely.com::1881462", "archived": false, "enabled": true, "updated_time": "2025-09-12T20:39:18.170572Z", "flag_key": "targeted-delivery-flag", "environment_key": "development", "environment_name": "Development", "environment_id": ENVIRONMENT_ID, "default_variation_key": "off", "default_variation_name": "Off", "revision": 6, "status": "running", "role": "admin", "approval_settings": {} } ``` ### Update rulesets Use the [Update the Ruleset for a Flag in an Environment](docId\:wpUSoZjCEhG6L1zPVvfhf) API endpoint. :::hint{type="warning"} For `PATCH` requests, first [Fetch the Ruleset for a Flag in an Environment](docId\:TxxX0KcGkrO_cG331nADs), 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. ::: Options include: `add`, `remove`, `replace`, `move`, `copy`, and `test`. **Endpoint** – `PATCH https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset` :::hint{type="info"} You must [disable your rule](docId\:lBGgyLcd2VSJnj0tVuWJI) before removing it. ::: **Example request** ```curl curl --request PATCH \ --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN' \ --header 'content-type: application/json-patch+json' \ --data ' [ { "op": "replace", "path": "/rules/landing_page_targeted_delivery/enabled", "value": true } ] ' ``` **Example response** ```json { "url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset", "update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset", "disable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/disabled", "rules": { "landing_page_targeted_delivery": { "key": "landing_page_targeted_delivery", "name": "Targeted Delivery for the landing page", "description": "", "variations": { "on": { "key": "on", "name": "On", "percentage_included": 10000, "variation_id": 1500954, "id": 6669615 } }, "baseline_variation_id": null, "type": "targeted_delivery", "id": 1598837, "urn": "rules.flags.optimizely.com::1598837", "archived": false, "enabled": true, "created_time": "2025-09-12T20:14:49.374112Z", "updated_time": "2025-09-12T20:26:05.310167Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [], "allow_list": {}, "layer_id": 9300001985290, "layer_experiment_id": 9300002731002, "status": "running" } }, "rule_priorities": [ "landing_page_targeted_delivery" ], "id": 1881462, "urn": "rulesets.flags.optimizely.com::1881462", "archived": false, "enabled": true, "updated_time": "2025-09-12T20:26:05.381855Z", "flag_key": "targeted-delivery-flag", "environment_key": "development", "environment_name": "Development", "environment_id": ENVIRONMENT_ID, "default_variation_key": "off", "default_variation_name": "Off", "revision": 4, "status": "running", "role": "admin" } ``` ### Disable rulesets Use the [Disable the Ruleset for a Flag in an Environment](docId\:FhzZpdoMEz9wx-0AZd5YF) API endpoint. **Endpoint** – `POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/disabled` **Example request** ```curl curl --request POST \ --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/disabled \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN' ``` **Example response** ```json { "url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset", "update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset", "enable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/enabled", "rules": { "landing_page_targeted_delivery": { "key": "landing_page_targeted_delivery", "name": "Targeted Delivery for the landing page", "description": "", "variations": { "on": { "key": "on", "name": "On", "percentage_included": 10000, "variation_id": 1500954, "id": 6669615 } }, "baseline_variation_id": null, "type": "targeted_delivery", "id": 1598837, "urn": "rules.flags.optimizely.com::1598837", "archived": false, "enabled": true, "created_time": "2025-09-12T20:14:49.374112Z", "updated_time": "2025-09-12T20:57:04.728173Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [], "allow_list": {}, "layer_id": 9300001985290, "layer_experiment_id": 9300002731002, "status": "running" } }, "rule_priorities": [], "id": 1881462, "urn": "rulesets.flags.optimizely.com::1881462", "archived": false, "enabled": false, "updated_time": "2025-09-12T20:57:04.728173Z", "flag_key": "targeted-delivery-flag", "environment_key": "development", "environment_name": "Development", "environment_id": ENVIRONMENT_ID, "default_variation_key": "off", "default_variation_name": "Off", "revision": 7, "status": "paused", "role": "admin" } ``` ### Enable rulesets Use the [Enable the Ruleset for a Flag in an Environment](docId:3EqUxeVRs0Ew1Pbe6yCII) API endpoint. **Endpoint** – `POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/enabled` **Example request** ```curl curl --request POST \ --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/enabled \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN' ``` **Example response** ```json { "url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset", "update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset", "disable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/disabled", "rules": { "landing_page_targeted_delivery": { "key": "landing_page_targeted_delivery", "name": "Targeted Delivery for the landing page", "description": "", "variations": { "on": { "key": "on", "name": "On", "percentage_included": 10000, "variation_id": 1500954, "id": 6669615 } }, "baseline_variation_id": null, "type": "targeted_delivery", "id": 1598837, "urn": "rules.flags.optimizely.com::1598837", "archived": false, "enabled": true, "created_time": "2025-09-12T20:14:49.374112Z", "updated_time": "2025-09-12T20:58:41.725828Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [], "allow_list": {}, "layer_id": 9300001985290, "layer_experiment_id": 9300002731002, "status": "running" } }, "rule_priorities": [], "id": 1881462, "urn": "rulesets.flags.optimizely.com::1881462", "archived": false, "enabled": true, "updated_time": "2025-09-12T20:58:41.725828Z", "flag_key": "targeted-delivery-flag", "environment_key": "development", "environment_name": "Development", "environment_id": ENVIRONMENT_ID, "default_variation_key": "off", "default_variation_name": "Off", "revision": 8, "status": "running", "role": "admin" } ``` ## Rules ### List rules in a project Use the [List Rules](docId\:nV9i0xt5kQyLKIp1gPT4U) API endpoint. **Endpoint** – `GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules` **Example request** ```curl curl --request GET \ --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN' ``` **Example response** ```json { "count": 6, "total_count": 6, "total_pages": 1, "url": "/projects/PROJECT_ID/rules", "page": 1, "items": [ { "key": "landing_page_targeted_delivery", "name": "Targeted Delivery for the landing page", "description": "", "variations": { "on": { "key": "on", "name": "On", "percentage_included": 10000, "variation_id": 1500954, "id": 6669615 } }, "baseline_variation_id": null, "type": "targeted_delivery", "id": 1598837, "urn": "rules.flags.optimizely.com::1598837", "archived": false, "enabled": true, "created_time": "2025-09-12T20:14:49.374112Z", "updated_time": "2025-09-12T20:58:41.725828Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [], "allow_list": {}, "group_remaining_traffic_allocation": 100, "layer_id": 9300001985290, "layer_experiment_id": 9300002731002, "status": "running", "project_id": PROJECT_ID, "group_id": "", "flag_key": "targeted-delivery-flag", "flag_name": "Targeted-delivery-flag", "flag_status": "unarchived", "environment_key": "development", "environment_name": "Development" }, { "key": "stock_message_test", "name": "Stock Message Test", "description": "", "variations": { "off": { "key": "off", "name": "Off", "percentage_included": 5000, "variation_id": 1500962, "id": 6669660 }, "on": { "key": "on", "name": "On", "percentage_included": 5000, "variation_id": 1500963, "id": 6669661 } }, "baseline_variation_id": null, "type": "a/b", "distribution_mode": "manual", "id": 1598853, "urn": "rules.flags.optimizely.com::1598853", "archived": false, "enabled": false, "created_time": "2025-09-12T20:39:20.565416Z", "updated_time": "2025-09-12T20:39:20.554081Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [ { "event_id": 5312230607028224, "scope": "visitor", "aggregator": "unique", "winning_direction": "increasing", "display_title": "add_to_cart", "id": "46135e38-8e67-4656-826b-b3343d564f03", "alias": "dca1a5a6b8ea8c1beca2648e739e306e5d6a9399b041cbee72594ce75ef84d0b", "visibility": "experiment", "project_id": PROJECT_ID, "updated_at": "2025-09-12T20:39:21.758625965Z", "account_id": ACCOUNT_ID } ], "allow_list": {}, "group_rule": { "group_id": 0, "traffic_allocation": 0 }, "group_remaining_traffic_allocation": 100, "layer_id": 9300001985314, "layer_experiment_id": 9300002731026, "status": "draft", "project_id": PROJECT_ID, "group_id": "", "flag_key": "a_b_test_flag", "flag_name": "a_b_test_flag", "flag_status": "unarchived", "environment_key": "development", "environment_name": "Development" }, { "key": "already-existing-a-b-test", "name": "Already-exisiting-a-b-test", "description": "", "variations": { "off": { "key": "off", "name": "Off", "percentage_included": 5000, "variation_id": 1500745, "id": 6669306 }, "on": { "key": "on", "name": "On", "percentage_included": 5000, "variation_id": 1500746, "id": 6669307 } }, "baseline_variation_id": 1500745, "type": "a/b", "distribution_mode": "manual", "id": 1598646, "urn": "rules.flags.optimizely.com::1598646", "archived": false, "enabled": true, "created_time": "2025-09-12T16:44:11.824135Z", "updated_time": "2025-09-12T19:51:52.213225Z", "audience_conditions": [ "or", { "audience_id": 5589361492754432 } ], "audience_ids": [ 5589361492754432 ], "percentage_included": 10000, "metrics": [ { "event_id": 5504179729334272, "scope": "visitor", "aggregator": "unique", "winning_direction": "increasing", "display_title": "PDP Page Views", "id": "2f7cd919-c73b-4a99-81c7-daa69e1cc2a6", "alias": "b20520c09877f956ad8a7ef7723139006f01174e69b253d1896c9d0a82ebe212", "visibility": "account", "updated_at": "2025-05-21T15:40:30.967744070Z", "account_id": ACCOUNT_ID } ], "fetch_results_ui_url": "https://app.optimizely.com/v2/projects/PROJECT_ID/results/RESULTS_ID/experiments/EXPERIMENT_ID?baseline=BASELINE_VARIATION_ID", "allow_list": {}, "group_rule": { "group_id": 0, "traffic_allocation": 0 }, "group_remaining_traffic_allocation": 100, "layer_id": 9300001984917, "layer_experiment_id": 9300002730629, "status": "running", "project_id": PROJECT_ID, "group_id": "", "flag_key": "doc-test-flag", "flag_name": "Doc test flag", "flag_status": "unarchived", "environment_key": "development", "environment_name": "Development" }, { "key": "mab_test", "name": "Multi-armed Test", "description": "", "variations": { "off": { "key": "off", "name": "Off", "percentage_included": 3333, "variation_id": 1500745, "id": 6668479 }, "on": { "key": "on", "name": "On", "percentage_included": 3333, "variation_id": 1500746, "id": 6668480 }, "on_hide_amounts": { "key": "on_hide_amounts", "name": "On Hide Amounts", "percentage_included": 3334, "variation_id": 1500757, "id": 6668481 } }, "baseline_variation_id": null, "type": "multi_armed_bandit", "id": 1598723, "urn": "rules.flags.optimizely.com::1598723", "archived": false, "enabled": false, "created_time": "2025-09-12T17:45:13.103056Z", "updated_time": "2025-09-12T19:40:45.033536Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [ { "event_id": 5504179729334272, "scope": "visitor", "aggregator": "unique", "winning_direction": "increasing", "display_title": "add_to_cart", "id": "ca56e5d6-b1ad-4ef2-94b6-7fb176fe20ac", "alias": "9ea078c4bef9300012b0f5452289d569f0b95bfa230168d9734424952199933a", "visibility": "experiment", "project_id": PROJECT_ID, "updated_at": "2025-09-12T17:45:14.341649449Z", "account_id": ACCOUNT_ID } ], "allow_list": {}, "group_rule": { "group_id": 0, "traffic_allocation": 0 }, "group_remaining_traffic_allocation": 100, "layer_id": 9300001985070, "layer_experiment_id": 9300002730782, "status": "draft", "project_id": PROJECT_ID, "group_id": "", "flag_key": "doc-test-flag", "flag_name": "Doc test flag", "flag_status": "unarchived", "environment_key": "development", "environment_name": "Development" }, { "key": "experiment", "name": "experiment", "description": "", "variations": { "off": { "key": "off", "name": "Off", "percentage_included": 5000, "variation_id": 1223804, "id": 5403098 }, "on": { "key": "on", "name": "On", "percentage_included": 5000, "variation_id": 1313957, "id": 5403099 } }, "baseline_variation_id": null, "type": "a/b", "distribution_mode": "manual", "id": 1428193, "urn": "rules.flags.optimizely.com::1428193", "archived": false, "enabled": true, "created_time": "2025-04-29T21:10:01.059880Z", "updated_time": "2025-04-29T21:10:26.370340Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [ { "event_id": 4987522074279936, "scope": "visitor", "aggregator": "unique", "winning_direction": "increasing", "display_title": "purchase", "id": "e4e94605-f780-4037-aaba-02e944732158", "alias": "9548e56d6c2f9a32a4152c8b33f946b6538460c53ec01da0bb54b39953443628", "visibility": "project", "project_id": PROJECT_ID, "updated_at": "2025-04-29T21:08:59.655557295Z", "description": "Purchase metric from the Python SDK quickstart.", "account_id": ACCOUNT_ID } ], "fetch_results_ui_url": "https://app.optimizely.com/v2/projects/PROJECT_ID/results/RESULTS_ID/experiments/EXPERIMENT_ID", "allow_list": {}, "group_rule": { "group_id": 0, "traffic_allocation": 0 }, "group_remaining_traffic_allocation": 100, "layer_id": 9300001661503, "layer_experiment_id": 9300002382064, "status": "running", "project_id": PROJECT_ID, "group_id": "", "flag_key": "product_sort", "flag_name": "Product sort", "flag_status": "unarchived", "environment_key": "production", "environment_name": "Production" }, { "key": "best_sort_method", "name": "Best sort method", "description": "", "variations": { "off": { "key": "off", "name": "Off", "percentage_included": 10000, "variation_id": 1223804, "id": 5112052 } }, "baseline_variation_id": null, "type": "a/b", "distribution_mode": "manual", "id": 1291104, "urn": "rules.flags.optimizely.com::1291104", "archived": false, "enabled": false, "created_time": "2025-04-14T21:44:42.781693Z", "updated_time": "2025-04-14T21:49:39.008847Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [ { "event_id": 10884603042, "scope": "visitor", "aggregator": "sum", "winning_direction": "increasing", "display_title": "Cross-project-metric", "id": "d790121e-de7f-41f0-a973-13e553f9c31c", "alias": "6a9b1b79a56a090b1e9e486712250c2d5511f388dedbf9c105a43a2979f66af3", "visibility": "account", "updated_at": "2025-04-17T23:42:38.214532319Z", "description": "A metric available across all projects. ", "account_id": ACCOUNT_ID } ], "allow_list": {}, "group_rule": { "group_id": 0, "traffic_allocation": 0 }, "group_remaining_traffic_allocation": 100, "layer_id": 9300001587905, "layer_experiment_id": 9300002212100, "status": "draft", "project_id": PROJECT_ID, "group_id": "", "flag_key": "product_sort", "flag_name": "Product sort", "flag_status": "unarchived", "environment_key": "development", "environment_name": "Development" } ], "last_url": "/projects/PROJECT_ID/rules", "first_url": "/projects/PROJECT_ID/rules" } ``` See the [List Rules](docId\:nV9i0xt5kQyLKIp1gPT4U) API reference documentation for optional query parameters. ### Fetch the rules for a ruleset by Feature Experimentation environment Use the [Fetch the Rule for a Ruleset in an Environment](docId\:YYvzC4lOorCtWiVhPKMmL) API endpoint. **Endpoint** – `GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/rules/RULE_KEY` **Example request** ```curl curl --request GET \ --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/rules/landing_page_targeted_delivery \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN' ``` **Example response** ```json { "key": "landing_page_targeted_delivery", "name": "Targeted Delivery for the landing page", "description": "", "variations": { "on": { "key": "on", "name": "On", "percentage_included": 10000, "variation_id": 1500954, "id": 6669615 } }, "baseline_variation_id": null, "type": "targeted_delivery", "id": 1598837, "urn": "rules.flags.optimizely.com::1598837", "archived": false, "enabled": true, "created_time": "2025-09-12T20:14:49.374112Z", "updated_time": "2025-09-12T20:58:41.725828Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [], "allow_list": {}, "layer_id": 9300001985290, "layer_experiment_id": 9300002731002, "status": "running", "experiment_id": 9300002731002, "environment_key": "development", "flag_key": "targeted-delivery-flag", "environment_name": "Development", "flag_name": "Targeted-delivery-flag" } ``` ### Read a rule for a specific experiment ID Use the [Fetch a Rule for a specific experiment\\\_id](docId\:E7_P_8NWk9Wh3k19PMZtE) API endpoint. **Endpoint** – `GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules/EXPERIMENT_ID` **Example request** ```curl curl --request GET \ --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules/EXPERIMENT_ID \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN' ``` **Example response** ```json { "key": "stock_message_test", "name": "Stock Message Test", "description": "", "variations": { "off": { "key": "off", "name": "Off", "percentage_included": 5000, "variation_id": 1500962, "id": 6669660 }, "on": { "key": "on", "name": "On", "percentage_included": 5000, "variation_id": 1500963, "id": 6669661 } }, "baseline_variation_id": null, "type": "a/b", "distribution_mode": "manual", "id": 1598853, "urn": "rules.flags.optimizely.com::1598853", "archived": false, "enabled": false, "created_time": "2025-09-12T20:39:20.565416Z", "updated_time": "2025-09-12T20:39:20.554081Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [ { "event_id": 5312230607028224, "event_type": "custom", "scope": "visitor", "aggregator": "unique", "winning_direction": "increasing", "display_title": "add_to_cart", "alias": "dca1a5a6b8ea8c1beca2648e739e306e5d6a9399b041cbee72594ce75ef84d0b", "id": "46135e38-8e67-4656-826b-b3343d564f03", "project_id": PROJECT_ID, "visibility": "experiment", "updated_at": "2025-09-12T20:39:21.758625965Z", "account_id": ACCOUNT_ID, "event_scoped": false } ], "allow_list": {}, "group_rule": { "group_id": 0, "traffic_allocation": 0 }, "group_remaining_traffic_allocation": 100, "layer_id": 9300001985314, "layer_experiment_id": 9300002731026, "status": "draft", "experiment_id": 9300002731026, "environment_key": "development", "flag_key": "a_b_test_flag", "environment_name": "Development", "flag_name": "a_b_test_flag" } ``` ## With the Feature Experimentation UI See [Manage rules](docId\:h1v5aDhM3KPn1_SyZ6e6W) in the user documentation.