Feature Experimentation API changelog – 2026
6 min
Subscribe to updates on this page using the notification and RSS feed options.
October 13, 2026 – API updates
Updated the Optimizely Feature Experimentation API and the Optimizely Flags Scheduling API to support change approvals, cross-project holdouts, flag lifecycle management, and richer experiment and custom field details.
Change approvals
Introduced the following endpoints to the Optimizely Flags Scheduling API to support change approvals, which route flag changes to designated reviewers before the changes reach production.
Approval policies:
Environment approval settings:
Approvals:
Change requests:
Updated the following endpoints to expose approval information on flag schedules and environments:
- Added the approver_assignment_mode, description, and default_preferences fields to the response. The default_preferences field includes the audiences, metrics, ramp_perc, rules, ruleset, and variations values.
- Added the approval_required and reason body parameters.
- Added the approval_status field to the response.
- Added the approval_status field to the response.
- Added the approval_status field to the response.
Updated the following endpoints to return a 409 response when a change requires approval or conflicts with an open approval request:
- Added the 409 response with the approval_settings, environment_key, error, flag_key, and reason fields.
- Added the 409 response with the approval_settings, environment_key, error, flag_key, and reason fields.
- Added the 409 response with the approval_settings, environment_key, error, flag_key, and reason fields.
- Updated the description to explain that the request is rejected with a 409 response when any flag in the batch has an open approval request. Nothing is archived in this case.
- Added the 409 response with the error, flag_keys, and message fields.
- Added the 409 response with the error, flag_keys, and message fields.
Holdouts
Introduced the following cross-project holdout endpoints to the Optimizely Feature Experimentation API so that a single holdout can cover rules in more than one project:
Updated the following holdout endpoints:
- Added the exclude_targeted_deliveries, project_ids, and rule_ids body parameters. Use exclude_targeted_deliveries to keep Targeted Delivery rules out of the holdout, because Targeted Deliveries represent permanent ship decisions.
- Removed the scope_type body parameter.
- Added the environment_name, exclude_targeted_deliveries, projects, rules, and url fields to the response.
- Removed the scope_type field from the response.
- Added the display_title field to each metric in the request and response.
- Updated the description to remove the reference to MetricsHub.
- Added the environment_name, exclude_targeted_deliveries, projects, rules, and url fields to the response.
- Removed the scope_type field from the response.
- Added the display_title field to each metric in the response.
- Added the environment_name, exclude_targeted_deliveries, projects, rules, and url fields to the response.
- Removed the scope_type field from the response.
- Added the display_title field to each metric in the response.
- Added the display_title field to the metrics in the request body.
- Updated the description to explain that audience conditions cannot be set on a holdout whose targeted rules span more than one project.
- Updated the description to remove the references to MetricsHub.
- Added the environment_name, exclude_targeted_deliveries, projects, rules, and url fields to the response.
- Removed the scope_type field from the response.
- Added the display_title field to each metric in the response.
- Added the deployed_variation_key and deployed_variation_name fields to the response.
Flags
Introduced the following endpoints to the Optimizely Feature Experimentation API:
- Validate a Ruleset update payload. Use this endpoint to run the same validation as the ruleset update endpoint without saving any changes.
Updated the following endpoints:
- Added the flag_status query parameter to filter flags by lifecycle status. Prefix a value with ! to exclude that status.
- Updated the descriptions of the team_ids and owner_user_id query parameters.
- Added the is_permanent field to the response.
- Removed the custom_fields field from the response.
- Added the is_permanent body parameter. Set is_permanent to true to mark a flag, such as a kill switch, as permanent so that governance tools exclude it from stale scoring and archive recommendations.
- Added the is_permanent field to the response.
- Removed the custom_fields field from the response.
- Added the is_permanent field to the response.
- Removed the custom_fields field from the response.
- Added the override_code_references body parameter.
- Added the restore and restored_from_revision_id query parameters. Use these parameters to record an update as a version restore in the History log.
- Added the display_title field to the metrics in the request body.
- Added the display_title field to the metrics in the request body.
- Added the display_title field to the metrics in the request body.
- Added the display_title field to the metrics in the request body.
Rules and experiments
Updated the following endpoints to expose experiment planning details:
- Added the custom_fields, hypothesis, test_plan_name, test_plan_type, and test_plan_url fields to the response.
- Added the display_title field to each metric in the response.
- Added the custom_fields, hypothesis, test_plan_name, test_plan_type, and test_plan_url fields to the response.
- Added the display_title field to each metric in the response.
- Added the custom_fields, hypothesis, test_plan_name, test_plan_type, and test_plan_url fields to the response.
- Added the display_title field to each metric in the response.
Files and variation screenshots
Introduced the following endpoints to the Optimizely Feature Experimentation API so that you can attach files, such as test plans and variation screenshots:
Updated the following endpoints:
- Added the screenshot_name and screenshot_url body parameters.
- Added the screenshot_name and screenshot_url fields to the response.
- Added the screenshot_name and screenshot_url fields to the response.
- Added the screenshot_name and screenshot_url fields to the response.
Custom fields
Updated the following endpoints to support validation rules and default values for custom fields:
- Added the archived, default_value, and validation body parameters. The validation object includes the allow_multi_select, decimal_places, field_options, max, max_length, min, regex, and use_thousand_separator values.
- Added the created_by_user_id, default_value, and validation fields to the response.
- Removed the archive_url, unarchive_url, update_url, and url fields from the response.
- Added the validation body parameter with the allow_multi_select and field_options values.
- Removed the required body parameter.
- Added the created_by_user_id, default_value, and validation fields to the response.
- Removed the archive_url, unarchive_url, update_url, and url fields from the response.
- Added the created_by_user_id, default_value, and validation fields to the response.
- Removed the archive_url, unarchive_url, update_url, and url fields from the response.
- Updated the description to explain that archived fields are excluded from required-value enforcement and that the required setting is preserved so that it is restored on unarchive.
- Added the created_by_user_id, default_value, and validation fields to the response.
- Removed the archive_url, unarchive_url, update_url, and url fields from the response.
- Added the created_by_user_id, default_value, and validation fields to the response.
- Removed the archive_url, unarchive_url, update_url, and url fields from the response.
Reports
Added the flag_state field to the responses of the following endpoints: