Manage rules
How to update rules in Optimizely Feature Experimentation.
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 and Rules 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 for information.
Rulesets
Read rulesets
Use the Fetch the Ruleset for a Flag in an Environment API endpoint.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT/ruleset
Request example
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'
Response example
{
"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": 761744660106841,
"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 API endpoint.
ImportantFor
PATCH
requests, first Fetch the Ruleset for a Flag in an Environment, merge only the fields you need to change, and then send thePATCH
. 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
NoteYou must disable your rule before removing it.
Request example
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
}
]
'
Response example
{
"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": 761744660106841,
"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 API endpoint.
Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/disabled
Request example
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'
Response example
{
"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": 761744660106841,
"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 API endpoint.
Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/enabled
Request example
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'
Response example
{
"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": 761744660106841,
"default_variation_key": "off",
"default_variation_name": "Off",
"revision": 8,
"status": "running",
"role": "admin"
}
Rules
List rules in a project
Use the List Rules API endpoint.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules
Example request
curl --request GET \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'
Example response
{
"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": 5629661695180800,
"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": 5629661695180800,
"updated_at": "2025-09-12T20:39:21.758625965Z",
"account_id": 10886221501
}
],
"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": 5629661695180800,
"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-exisiting-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": 10886221501
}
],
"fetch_results_ui_url": "https://app.optimizely.com/v2/projects/5629661695180800/results/9300001984917/experiments/9300002730629?baseline=1500745",
"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": 5629661695180800,
"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": 5629661695180800,
"updated_at": "2025-09-12T17:45:14.341649449Z",
"account_id": 10886221501
}
],
"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": 5629661695180800,
"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": 5629661695180800,
"updated_at": "2025-04-29T21:08:59.655557295Z",
"description": "Purchase metric from the Python SDK quickstart.",
"account_id": 10886221501
}
],
"fetch_results_ui_url": "https://app.optimizely.com/v2/projects/5629661695180800/results/9300001661503/experiments/9300002382064",
"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": 5629661695180800,
"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": 10886221501
}
],
"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 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 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 --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
{
"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 API endpoint.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules/EXPERIMENT_ID
Example request
curl --request GET \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules/9300002731026 \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'
Example response
{
"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 in the user documentation.
Updated 7 days ago