API Documentation

Submit Change Request

post
https://api.split.io/internal/api/v2/changeRequests/ws//environments/

Submit a change to a feature flag or segment for approval. No query parameters are required.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

To schedule a change request for future execution, include scheduledFor and (optionally) scheduledForTimezone in the request body. scheduledFor is an absolute point in time and is not affected by time zone. scheduledForTimezone only controls how the time is displayed in the Harness FME UI; if omitted, the scheduled time is displayed in UTC. 

"scheduledFor": 1786201200000,
"scheduledForTimezone": "America/Los_Angeles"

The timezone must be a valid IANA time zone identifier, such as America/New_York or Europe/London.

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]"],
    "scheduledFor": 1786201200000,
    "scheduledForTimezone": "America/Los_Angeles"
  }'

Scheduling fields are optional. scheduledFor is a Unix timestamp in milliseconds representing the scheduled execution time. If omitted, the change request behaves as it does today.

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'
Path Params
string
required

The ID of the project (previously called workspace) you would like to submit a change request in. After migration to Harness, get this value using the Get Projects (Workspaces) endpoint and the Harness project name.

string
required

The ID of the environment you would like to submit a change request in.

Body Params
integer

Optional. Unix timestamp in milliseconds marking the exact date and time the approved change request executes. This is an absolute point in time and does not change based on scheduledForTimezone.

string

Optional. IANA time zone for scheduledFor, such as America/Los_Angeles, used only to display the scheduled time in the UI. It does not affect when the change request executes. Defaults to UTC if omitted. Invalid time zones are rejected.

Responses

Updated 9 days ago

Language
LoadingLoading…
Response
Choose an example:
application/json

Updated 9 days ago