Access requirements

The Authorization Bearer (Admin API Key authorizing the request) must have one of the following roles and scopes:

Admin API Key roles accepted

API_ALL_GRANTED
API_FEATURE_FLAG_EDITOR*
API_SEGMENT_EDITOR**

Admin API Key scopes accepted

GLOBAL
WORKSPACE
ENVIRONMENT

* Accepted when the ChangeRequest is associated to a Split objectType.
** Accepted when the ChangeRequest is associated to a segment or largeSegment objectType.

Project (Workspace) View Restrictions may apply to this API.

To learn more about Admin API Key roles and scopes, see API keys overview.

Below are some examples of the expected payload for other types of updates to feature flags, Standard segments, and Large segments.

Feature flags

Open Change Request to modify an existing feature flag definition

curl --request POST 'https://api.split.io/internal/api/v2/changeRequests/ws/{workspace-id}/environments/{environment_id}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ADMIN_API_KEY' \ --data-raw '{ "split": {"name":"admin", "treatments":[{"name":"on","configurations":"{\"color\":\"blue\"}"},{"name":"off","configurations": "{\"color\":\"red\"}"}],"defaultTreatment":"off", "baselineTreatment": "off","rules":[{"buckets":[{"treatment":"on","size":50},{"treatment":"off","size":50}],"condition":{"matchers":[{"type":"IN_SEGMENT","string":"employees"}]}}],"defaultRule":[{"treatment":"off","size":50},{"treatment":"on","size":50}]}, "operationType":"UPDATE", "title":"update split definition", "comment":"update split definition", "approvers":["approvers email address"] } '

Open Change Request to kill a feature flag

curl --location --request POST 'https://api.split.io/internal/api/v2/changeRequests/ws/{workspace-id}/environments/{environment_id}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ADMIN_API_EY' \ --data-raw '{ "{ "split": {"name":"admin"}, "operationType":"KILL", "title":"kill split submission", "comment":"a great Comment", "approvers":["approvers email address"] } '

Open Change Request to restore a feature flag

curl --request POST 'https://api.split.io/internal/api/v2/changeRequests/ws/{workspace-id}/environments/{environment_id}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ADMIN_API_KEY' \ --data-raw '{ "split": {"name":"<SPLIT_NAME>"}, "operationType":"RESTORE", "title":"restore split", "comment":"a great comment", "approvers":["validUserEmail@sample.com"] } '

Open Change Request to archive a feature flag definition

curl --request POST 'https://api.split.io/internal/api/v2/changeRequests/ws/{workspace-id}/environments/{environment_id}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ADMIN_API_KEY' \ --data-raw '{ "split": {"name":"<SPLIT_NAME>"}, "operationType":"ARCHIVE", "title":"Some CR Title", "comment":"Some CR Comment", "approvers":["validUserEmail@sample.com"] } '

Standard segments

Open Change Request to add members to a Standard segment

curl --request POST 'https://api.split.io/internal/api/v2/changeRequests/ws/{workspace-id}/environments/{environment_id}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ADMIN_API_KEY' \ --data-raw '{ "segment":{"name":"<STANDARD_SEGMENT_NAME>", "keys":["k1","k2"]}, "operationType":"CREATE", "title":"Some CR Title", "comment":"Some CR Comment", "approvers":["validUserEmail@sample.com"] } '

Open Change Request to add members to a Standard segment via CSV

curl --request POST 'https://api.split.io/internal/api/v2/changeRequests/ws/{workspace-id}/environments/{environment_id}' \ --header 'Authorization: Bearer ADMIN API KEY' \ --form 'file=@/Users/someuser/approvalFlowsKeys.csv' \ --form 'segmentName=<STANDARD_SEGMENT_NAME>' \ --form 'title=Some CR Title' \ --form 'comment=Some CR Comment' \ --form 'approvers=validUserEmail_1@sample.com,validUserEmail_2@sample.com' \ --form 'operationType=CREATE'

Open Change Request to remove members from a Standard segment

curl --location --request POST 'https://api.split.io/internal/api/v2/changeRequests/ws/{workspace-id}/environments/{environment_id}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ADMIN_API_KEY' \ --data-raw '{ "segment":{"name":"<STANDARD_SEGMENT_NAME>", "keys":["k1","k2"]}, "operationType":"ARCHIVE", "title":"Some CR Title", "comment":"Some CR Comment", "approvers":["validUserEmail@sample.com"] } '

Large segments

Open Change Request to remove all members from a Large segment

curl --location --request POST 'https://api.split.io/internal/api/v2/changeRequests/ws/{workspace-id}/environments/{environment_id}' \ --header 'Authorization: Bearer ADMIN_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "largeSegment":{"name":"<LARGE_SEGMENT_NAME>"}, "operationType":"ARCHIVE", "title":"Archiving all user IDs (keys)", "comment":"Emptying this Large segment, as it is not in use anymore", "approvers":[] } '

Open Change Request to add members to a Large Segment

curl --location --request POST 'https://api.split.io/internal/api/v2/changeRequests/ws/{workspace-id}/environments/{environment_id}' \ --header 'Authorization: Bearer ADMIN_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "largeSegment":{"name":"<LARGE_SEGMENT_NAME>"}, "operationType":"UPLOAD", "title":"Create a new Large Segment version", "comment":"Change Request for upload user IDs (keys). This will create a new Large Segment version.", "approvers":[] }'

The response will provide parameters that you will use to build the upload request.

Example of the response:

{ "split": null, "segment": null, "largeSegment": { "id": "92b06147-98a8-11ef-a769-4a39a217f312", "name": "large_segment_name", "environment": { "id": "0a7f1900-9897-11ef-b6ae-12ee244cfa63", "name": "production" }, "trafficType": { "id": "0a6aa6a0-9897-11ef-b6ae-12ee244cfa63", "name": "user" }, "creationTime": 1730503525473 }, "id": "a9a83af0-98b2-11ef-bb38-8a4dd94d2dce", "status": "AWAITING", "title": "Add keys to large segment", "comment": null, "workspace": { "id": "0a659d90-9897-11ef-b6ae-12ee244cfb74", "type": "workspace" }, "approvers": [], "operationType": "UPLOAD", "comments": [], "rolloutStatus": null, "rolloutStatusTimestamp": null, "transactionMetadata": { "headers": { "Host": [ "<<Host header>>" ] }, "txId": "a9b2fd3b-98b2-11ef-97df-7e0035b4bcdb", "transactionDetails": { "status": "AWAITING_UPLOAD", "countDiff": 0, "totalKeys": 0, "changeNumber": 0, "processedSize": 0, "rawSize": 0, "filteredKeys": 0, "expiresAt": "2024-11-02T00:42:39Z" }, "method": "PUT", "url": "<<Upload URL>>" } }

The <<Upload URL>> has 5 minutes time to live (TTL). The url must be used within this 5 minute time window, before the url expires.

Use the <<Upload URL>> and <<Host header>> values to prepare the upload request to upload a CSV file.

curl --location --request PUT '<<Upload URL>>' \ --header 'Host: <<Host header>>' \ -T'large_segment.csv'