post
https://api.split.io/internal/api/v2/changeRequests/ws//environments/
Submit a change to a feature flag or segment for approval. Provide the change request details in the JSON body; no query parameters are required.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
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
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 limit feature flag exposure (traffic allocation)
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 '{
"split": {
"name": "your_feature_flag_name",
"treatments": [
{"name": "on"},
{"name": "off"}
],
"defaultTreatment": "off",
"baselineTreatment": "off",
"trafficAllocation": 75,
"defaultRule": [
{"treatment": "off", "size": 100}
]
},
"operationType": "UPDATE",
"title": "Set traffic allocation to 75%",
"comment": "Limiting exposure for gradual rollout",
"approvers": ["[email protected]"]
}'
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":["[email protected]"]
}
'Open Change Request to delete 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":["[email protected]"]
}
'Archive Operation Type
The ARCHIVE operation type represents a legacy definition deletion operation in change requests and is not related to the Feature Flag Archive API.
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":["[email protected]"]
}
'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 '[email protected],[email protected]' \
--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":["[email protected]"]
}
'Archive Operation Type
The ARCHIVE operation type is retained for historical compatibility and represents a removal operation in this context.
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":[]
}
'Archive Operation Type
The ARCHIVE operation type is a legacy operation label and does not archive the Large segment resource itself.
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'