Split docs

Suggest Edits

Introduction

 

This section details Split's API. The Split API uses resource-oriented URLs, uses status codes to indicate the success or failure of requests and returns JSON from all requests.

You can use the Split API to push data into Split, get data out of Split, build custom integrations, or build on top of the Split platform.

Getting Started?

If you're just getting started with Split, we encourage your to read our main documentation site. You'll learn how to set up our SDKs and release a feature without re-deploying your application.

Suggest Edits

Authentication

How to authenticate against the Split API

 

All requests to Split's API must be authenticated with an admin API key. The admin key type provides private and universal access to current and future admin APIs. Creating an API key is simple and can be done in the API Keys section of settings.

Learn more about API keys

To best familiarize yourself with using API keys in Split, visit our main documentation for more details.

Authentication Header

An authentication header must be added containing your API key for the request. Authenticate with the API by adding an authorization header containing your admin API key.

Authorization: Bearer ADMIN_API_KEY
Suggest Edits

Rate Limiting

 

Our public API is guarded by a rate limiter using several techniques to prevent abuse. Calls to this API that are rate limited will return a 429 status code along with relevant headers that indicate the remaining quota (X-RateLimit-Remaining-Org and X-RateLimit-Remaining-IP) and how long to wait until the next window specified in seconds (X-RateLimit-Reset-Seconds-Org and X-RateLimit-Reset-Seconds-IP). When rate limited, users should retry after a number of seconds equal to or greater than the maximum time of the last two "X-RateLimit-Reset-Seconds-XXX" headers.

API rate limiting and SDKs

Rate-limiting only applies to this public API and does not affect the API used by the SDKs to serve feature evaluations.

Suggest Edits

Get Workspaces

Retrieves the Splits for an organization.

 
gethttps://api.split.io/internal/api/v2/workspaces
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/workspaces
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "objects": [
        {
            "id": "757acff0-ec28-11e8-8376-1236ea496962",
            "name": "Default Workspace"
        },
        {
            "id": "788d8610-12a7-11e9-b1ee-0ed50fa918ca",
            "name": "ZzzzZ"
        },
        {
            "id": "6cdb71b0-12a7-11e9-b1ee-0ed50fa918ca",
            "name": "aaa"
        },
        {
            "id": "995b1830-ec46-11e8-94e9-0ed50fa918ca",
            "name": "test ws"
        }
    ],
    "offset": 0,
    "limit": 20,
    "totalCount": N
}
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error listing workspaces",
    "transactionId": "9ohbr8wmzf"
}

Query Params

offset
string

The offset to retrieve. Useful for pagination

limit
string

The maximum limit to return per call. Max=20.

 
Suggest Edits

Environments Overview

 

An environment reflects a stage in the development process, such as your production application or your internal staging environment. During the feature release process, Splits can be promoted through the various environments; allowing for a targeted roll out throughout the development process.

At this time the creation and editing of environments are limited to administrators within the Split application.

With the API you can get information about the environments that exist within your organization.

{
  "id": "string", // Server populated identifier
  "name": "string", // Display name
  "production": "boolean" // Production environment or not
}
Suggest Edits

Get Environments

Get a list of environments.

 
gethttps://api.split.io/internal/api/v2/environments/ws/wsId
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/environments/ws/<WORKSPACE_ID>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[ 
  {
    id: <string>,
    name: <string>
  },
  …
]


{
  "code": 404,
}

Path Params

wsId
string
required

The Id of the workspace you want to get an environment from

 
Suggest Edits

Create Environment

Create an environment

 
posthttps://api.split.io/internal/api/v2/environments/ws/wsId
curl -v -X POST -d '{"name":"new_environment","production":"false}' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/environments/ws/<WORKSPACE_ID>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[ 
  {
    id: <string>,
    name: <string>,
    production: <boolean>
  },
  …
]


{
  "code": 404,
}

Path Params

wsId
string
required

The id of the workspace you want to create an environment in

Form Data

environment
json
required

JSON object that contains the name of the environment

 
Suggest Edits

Delete Environment

Delete an environment

 
deletehttps://api.split.io/internal/api/v2/environments/ws/wsId/environment_name_or_id
curl -v -X DELETE \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/environments/ws/<WORKSPACE_ID>/{environment_name_or_id}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[ 
  {
    id: <string>,
    name: <string>
  },
  …
]


{
  "code": 404,
}

Path Params

environment_name_or_id
string
required

Environment name or Id

wsId
string
required

The id of the workspace you want to delete the environment from

 
Suggest Edits

Update Environment

Update an environment

 
patchhttps://api.split.io/internal/api/v2/environments/ws/wsId/environment_name_or_id
curl -v -X PATCH \
  -H 'Content-Type:application/json' \
  -d '[{"op": "replace", "path": "/name", "value":"NewName"}]' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/environments/ws/<WORKSPACE_ID>/OldName
curl -v -X PATCH \
  -H 'Content-Type:application/json' \
  -d '[{"op": "replace", "path": "/type", "value":"production"}]' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/environments/ENVIRONMENT_NAME
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[ 
  {
    id: <string>,
    name: <string>,
    production: <boolean>
  }
]


{
  "code": 404,
}

Path Params

environment_name_or_id
string
required

Environment name or ID

wsId
string
required

The id of the workspace you want to update the environment from

Form Data

update_environment
json
required

JSON object that contains the attributes of a environment to be updated in JsonPatch format

 
Suggest Edits

Traffic Types Overview

 

A traffic type is a particular identifier type for any hierarchy of your customer base. Traffic types in Split are completely customizable and can be any database key you choose to send to Split, i.e. a user ID, account ID, IP address, browser ID, etc. Essentially, any internal database key you're using to track what "customer" means to you.

The creation and editing of traffic types are limited to administrators within the Split application.

With the API you can get information about the traffic types that exist within your organization.

Learn more about traffic types

To best familiarize yourself with using traffic types, visit our main documentation for more details.

{
  "id": "string", // Server populated identifier
  "name": "string", // Display name
  "displayAttributeId": "string" // (Optional) Attribute used for display name in UI
}
Suggest Edits

Get Traffic Types

Get a list of traffic types.

 
gethttps://api.split.io/internal/api/v2/trafficTypes/ws/wsId
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/trafficTypes
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
	{
		id: <string>,
		name: <string>,
		displayAttributeId: <string>
	},
	…
]

{
  "code": 404,
}

Path Params

wsId
string
required

The id of the workspace you want to get traffic types from

 
Suggest Edits

Attributes Overview

 

Attributes are properties of a customer id in Split. With the API you can get, save, and delete attributes programmatically.

Attribute fields are also created automatically when new customer identities are saved to Split. Those newly created attributes are created with an unknown data type and with no display or description information. It is recommended to customize and/or update your attributes to ensure each attribute has a data type and attribute description.

The data type is an optional parameter which is used for display formatting purposes. This parameter is not used to validate the values on inbound customer identities, but incorrectly typed data will be displayed as their raw string. The data types available include string, datetime, number, and set; this value can also be left null and the data will be treated as a string. Values for datetime fields are expected to be passed as milliseconds past the epoch. Values for set fields are expected to be passed in a string as comma separated values. If an unsupported data type is sent you will receive a 400 error code as a response.

{
  "id": "string", // Attribute identifier, same as used in identity value map
  "trafficTypeId": "string", // Traffic type this attribute is associated with
  "displayName": "string", // (Optional) How the attribute will be displayed in the UI, defaults to the id
  "description": "string", // (Optional) A description of the attribute
  "dataType": "string", // (Optional) The data type of the attribute used for display formatting, defaults to displaying the raw string. Must be one of: null, "string", "datetime", "number", "set"
  "isSearchable": boolean // (Optional) If the attribute should appear in segment and whitelist search
}
Suggest Edits

Get Attributes

Get a list of attributes via JSON for a traffic type ID.

 
gethttps://api.split.io/internal/api/v2/schema/ws/ws_id/trafficTypes/traffic_type_id_or_name
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
 https://api.split.io/internal/api/v2/schema/ws/<WS_ID>/trafficTypes/<TRAFFIC_TYPE_ID_OR_NAME>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
	{
		id: <string>,
		trafficTypeId: <string>,
		displayName: <string>,
		description: <string>,
		dataType: <string>
	},
	...
]
{
  "code": 404,
}

Path Params

traffic_type_id
string
required

The ID of the traffic type to fetch attributes from

ws_id
string
required

The id of the workspace you want attributes from

 
Suggest Edits

Save Attribute

Save an attribute for a traffic type ID. The attribute is created if it does not exist and is overwritten completely if it does.

 
posthttps://api.split.io/internal/api/v2/schema/ws/ws_id/trafficTypes/traffic_type_id_or_name
curl -v -X POST \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  -d '{ "id": <string>, "trafficTypeId": <string>, "displayName": <string>, "description": <string>, "dataType": <string> }' \
  https://api.split.io/internal/api/v2/schema/ws/<WS_ID>/trafficTypes/<TRAFFIC_TYPE_ID_OR_NAME>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  id: <string>,
  trafficTypeId: <string>,
  displayName: <string>,
  description: <string>,
  dataType: <string>
}
{
  "code": 404,
}

Path Params

traffic_type_id
string
required

The ID of the traffic type to the attribute is associated with

ws_id
string
required

The id of the workspace you want to add attributes to

 

Request format

Suggest Edits

Delete Attribute

Delete an attribute by its traffic type and attribute ID. This also removes any stored data for that attribute from all customer identities in Split.

 
deletehttps://api.split.io/internal/api/v2/schema/ws/ws_id/trafficTypes/traffic_type_id_or_name/attribute_id
curl -v -X DELETE \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/schema/ws/<WS_ID>/trafficTypes/<TRAFFIC_TYPE_ID_OR_NAME>/<ATTRIBUTE_ID>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
true
{
  "code": 404,
}

Path Params

traffic_type_id
string
required

The ID of the traffic type to delete the attribute from.

attribute_id
string
required

The ID of the attribute to delete.

ws_id
string
required

the id of the workspace where the attribute you want to delete is

 
Suggest Edits

Customer Identities Overview

 

You can populate your customer identities within Split to enrich and simplify the experience when using the Split web console. Learn more about using this data in Split.

Your customer ids and information are used to help search for customers during segment and whitelist creation as well when navigating impressions for any Split.

With the API you can save, update and delete customer identities programmatically. 

{
  key: "string", // Key used for getTreatment() calls
  trafficTypeId: "string", // Traffic Type Identifier
  environmentId: "string", // Environment Identifier
  values: { // Attribute Values (key: Attribute Id, value: value)
    key: "string",
    ...
  }
}
Suggest Edits

Save Customer Identity

Create or overwrite a single customer ID for a given traffic type and environment.

 
posthttps://api.split.io/internal/api/v2/trafficTypes/traffic_type_id/environments/environment_id/identities/key
curl -v -X PUT \
  -H 'Content-Type:application/json' \
  -d '{ key: <string: key>, values: { <string: attribute_id>: <string: value>, ... } }' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/trafficTypes/<TRAFFIC_TYPE_ID>/environments/<ENVIRONMENT_ID>/identities/<KEY>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
	key: <string: key>,
	trafficTypeId: <string: type id>,
	environmentId: <string: environment id>,
	values: {
		<string: attribute_id>: <string: value>,
		...
	}
}
{
  "code": 404,
}

Path Params

traffic_type_id
string
required

The ID of the traffic type to add the Identities within.

environment_id
string
required

The ID of the environment to add the identities within.

key
string
required

The key used for getTreatment calls for the object this identity represents

 
Suggest Edits

Save Customer Identities

Create or overwrite customer identities for a given traffic type and environment.

 
posthttps://api.split.io/internal/api/v2/trafficTypes/traffic_type_id/environments/environment_id/identities
curl -v -X POST \
  -H 'Content-Type:application/json' \
  -d '[{ key: <string: key>, values: { <string: attribute_id>: <string: value>, ... } }, ... ]' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/trafficTypes/<TRAFFIC_TYPE_ID>/environments/<ENVIRONMENT_ID>/identities/
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  objects: [ 
    {
      key: <string: key>,
      trafficTypeId: <string: type id>,
      environmentId: <string: environment id>,
      values: {
        <string: attribute_id>: <string: value>,
        ...
      }
    },
    …
  ]
}
{
  "code": 404,
}

Path Params

traffic_type_id
string
required

The ID of the traffic type to add the identities within.

environment_id
string
required

The ID of the environment to add the identities within.

 
Suggest Edits

Update Customer Identity

Update a single customer ID for a given traffic type and environment. Any provided attribute values will be overwritten, but existing values will otherwise remain.

 
patchhttps://api.split.io/internal/api/v2/trafficTypes/traffic_type_id/environments/environment_id/identities/key
curl -v -X PATCH \
  -H 'Content-Type:application/json' \
  -d '{ key: <string: key>, values: { <string: attribute_id>: <string: value>, ... } }' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/trafficTypes/<TRAFFIC_TYPE_ID>/environments/<ENVIRONMENT_ID>/identities/<KEY>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
	key: <string: key>,
	trafficTypeId: <string: type id>,
	environmentId: <string: environment id>,
	values: {
		<string: attribute_id>: <string: value>,
		...
	}
}
{
  "code": 404,
}

Path Params

traffic_type_id
string
required

The ID of the traffic type to add the identities within.

environment_id
string
required

The ID of the environment to add the identities within.

key
string
required

The key used for getTreatment calls for the object this identity represents

 
Suggest Edits

Delete Customer Identity

Delete a customer ID from a given traffic type and environment.

 
deletehttps://api.split.io/internal/api/v2/trafficTypes/traffic_type_id/environments/environment_id/identities/key
curl -v -X DELETE \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/trafficTypes/<TRAFFIC_TYPE_ID>/environments/<ENVIRONMENT_ID>/identities/<KEY>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
true
{
  "code": 404,
}

Path Params

traffic_type_id
string
required

The ID of the traffic type to delete the Attribute from

environment_id
string
required

The ID of the environment to add the Identities within.

key
string
required

The key used for getTreatment calls for the object this identity represents

 
Suggest Edits

Segments Overview

 

The Rest API allows you to manage your Segments programmatically.

Using this API you can get Segments, as well as update a Segments keys in an environment.

Learn more about segments

To best familiarize yourself with using Segments in your deployment and rollout strategy, visit our main documentation for more details.

Suggest Edits

Segment

 

Below is the configuration for a Segment in a specific environment such as production or staging.

Note that Segments can be configured differently for each environment.

{
    "name": String,
    "environment": { "id": String, "name": String }, 
    "trafficType": { "id": String, "name": String }, 
    "creationTime": Number 
}
Suggest Edits

List Segments in Environment

Retrieves the Segments given an environment.

 
gethttps://api.split.io/internal/api/v2/segments/ws/wsId/environments/environment_id_or_name
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/segments/ws/<WORKSPACE_ID>/environments/Production
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "objects": [
      	{
          	"name":"demo",
          	"environment": { ... },
          	"trafficType": { ... },
          	"creationTime":1493920102896
        },
        { ... }
    ],
    "offset": 0,
    "limit": 20,
    "totalCount": N
}
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error listing segments for environment Production",
    "transactionId": "9ofcp0yvpb"
}
{
    "code": 404,
    "message": "Could not find environment Production",
    "transactionId": "9ofdd0bn9m"
}

Path Params

environment_id_or_name
string
required

The id or case sensitive name of the environment in which you want get the segments

wsId
string
required

The id of the workspace for your environment

Query Params

offset
int32

The offset to retrieve. Useful for pagination

limit
string

The maximum segments to return per call. Max=50.

 

JSON Received 

{
    "objects": [ SEGMENT_IN_ENVIRONMENT ], // Array of Segments returned
    "offset": Number, // Offset received
    "limit": Number, // Limit received
    "totalCount": Number // Total number of Segments for the environment
}
Suggest Edits

Update Segment Keys in Environment via CSV

Bulk upload a CSV file containing a list of identifiers. The segment must exist before calling this endpoint.

 
puthttps://api.split.io/internal/api/v2/segments/environment_id/segment_name/upload?replace=false
curl -v -X PUT \
	-F "file=@/tmp/segments.csv" \
	-H 'Authorization: Bearer ADMIN_API_KEY' \
	https://api.split.io/internal/api/v2/segments/<ENVIRONMENT_ID>/segment_1/upload
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "dcaf31f0-ce9b-11e5-b8fa-6ee57757bd75",
  "orgId": "9b3df640-9adc-11e5-a8b2-aa398de8870a",
  "environment": "9dee9750-9adc-11e5-a8b2-aa398de8870a",
  "name": "segment_1",
  "trafficTypeId": "u",
  "trafficTypeURN": {
    "type": "TRAFFIC_TYPE",
    "id": "u",
    "name": "user"
  },
  "description": "Created by API",
  "creator": {
    "type": "System",
    "id": "Root",
    "name": "split.io"
  },
  "status": "ACTIVE",
  "creationTime": 1454960452239,
  "lastUpdateTime": 1454960453619,
  "iAmInThisSegment": null
}
{
  "code": 404,
  "message": "There is no segment with name $segment_name in environment $environment_id"
}

Path Params

environment_id
string
required

The id of the environment to upload the segment to

segment_name
string
required

The name of the segment you want to create

Query Params

replace
boolean

Replace the content of the segment (if it previously exists) with the new content

Form Data

file
string

The location of the file to upload

 
Suggest Edits

Update Segment Keys in Environment via JSON

Bulk upload a list of identifiers via JSON to a segment. The segment must exist before calling this endpoint.

 
puthttps://api.split.io/internal/api/v2/segments/environment_id/segment_name/upload?replace=false
curl -v -X PUT \
  -H 'Content-Type:application/json' \
  -d '["id1", "id2", "id3"]' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/segments/<ENVIRONMENT_ID>/segment_1/upload
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "dcaf31f0-ce9b-11e5-b8fa-6ee57757bd75",
  "orgId": "9b3df640-9adc-11e5-a8b2-aa398de8870a",
  "environment": "9dee9750-9adc-11e5-a8b2-aa398de8870a",
  "name": "segment_1",
  "trafficTypeId": "u",
  "trafficTypeURN": {
    "type": "TRAFFIC_TYPE",
    "id": "u",
    "name": "user"
  },
  "description": "Created by API",
  "creator": {
    "type": "System",
    "id": "Root",
    "name": "split.io"
  },
  "status": "ACTIVE",
  "creationTime": 1454960452239,
  "lastUpdateTime": 1454960453619,
  "iAmInThisSegment": null
}
{
  "code": 404,
  "message": "There is no segment with name $segment_name in environment $environment_id"
}

Path Params

environment_id
string
required

The id of the environment to upload the segment to

segment_name
string
required

The name of the segment you want to create

Query Params

replace
boolean

Replace the content of the segment (if it previously exists) with the new content

 

Request format 

["id_1", "id_2", "id_3", .... ]
Suggest Edits

Get Segment Keys in Environment

Retrieve segments keys for a given existing segment.

 
gethttps://api.split.io/internal/api/v2/segments/environment_id/segment_name/keys
curl -v -X GET \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/segments/<ENVIRONMENT_ID>/segment_1/keys
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "keys": [
    {
      "key": "key_1"
    },
    {
      "key": "key_2"
    },
    {
      "key": "key_3"
    },
    {
      "key": "key_4"
    },
    {
      "key": "key_5"
    }
  ],
  "count": 200,
  "offset": 5,
  "limit": 5
}
{
  "code": 404,
  "message": ""
}

Path Params

environment_id
string
required

The id of the environment to read segment keys from

segment_name
string
required

The name of the segment you want to fetch keys from

Query Params

offset
int32

The offset to retrieve. Useful for pagination

limit
int32

The maximum keys to return per call. Max=100.

 
Suggest Edits

Remove Segment Keys from Environment

Delete a list of segment keys via JSON from an existing segment.

 
puthttps://api.split.io/internal/api/v2/segments/environment_id/segment_name/deleteKeys
curl -v -X PUT \
  -H 'Content-Type:application/json' \
  -d '["id1", "id2", "id3"]' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/segments/<ENVIRONMENT_ID>/segment_1/deleteKeys
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "code": 200,
  "message": ""
}
{
  "code": 404,
  "message": "There is no segment with name $segment_name in environment $environment_id"
}

Path Params

environment_id
string
required

The id of the environment to delete segment keys from

segment_name
string
required

The name of the segment you want to delete keys from

 

Request format 

["id_1", "id_2", "id_3", .... ]
Suggest Edits

Splits Overview

 

The Rest API allows you to manage your Splits programmatically.

Using this API, you can create, get, delete Splits, as well as update a Split's targeting definition in an Environment.

Learn more about Splits

To best familiarize yourself with using Splits in your deployment and rollout strategy, visit our main documentation for more details

Suggest Edits

Split

 

A Split is our term for a feature flag, toggle, or experiment. In REST terms it has the following schema: 

{
    "name": String,
    "description": String, 
    "trafficType": { "id": String, "name": String }, 
    "creationTime": Number,
    "tags" : [{ "name": String }]
}

The REST Endpoints available for a Split are:

It's worth noting that this object does not contain any information regarding the configuration or rollout plan for any specific environment.

In the same way as the web console, creating a Split involves setting a name and a traffic type (and possibly a description).

After the Split is created, it is possible to update it for any specific environment, using the REST API calls for Split Definition.

Suggest Edits

Split Definition

 

A Split Definition is the configuration of a Split in a specific environment such as production or staging.

{
	“name”: String,
	“environment”: { "id": String, "name": String },
 	“trafficType“: { "id": String, "name": String },
	“killed”: Boolean,
	“treatments”: [ Treatment ],
	“defaultTreatment”: String,
	“trafficAllocation”: Number,
	“rules”: [ Rule ], 
	“defaultRule”: [ Bucket ],
	“creationTime”: Number,
	“lastUpdateTime”: Number,
}

The minimum required fields for configuring a Split Definition are treatments, defaultTreatment, and defaultRule.

For detailed examples on how to perform actions on a Split Definition, check:

Suggest Edits

Treatment

 

A treatment is a state of a Split. A simple feature flag has two treatments: on and off. An experiment can have any number of treatments.

{
  “name”: String,
  “description”: String,
  “keys”: [ String ],
  “segments”: [ String ]
}

Keys are used to show the specified treatment for a specific customer. It is analogous to the Whitelist section on the Web Console.

In the same way, Segments is used to show the treatment to users in a particular segment.

Suggest Edits

Rule

 

A Rule consists of a Condition and a list of Buckets.

When the Split Definition is evaluated, if the Condition of this Rule is met, then the customer will be evaluated and fall in the sticky distribution specified in the Buckets

{
  “condition”: Condition,
  “buckets”: [ Bucket ]
}

Note that you do not need to provide all treatments for each rule, however, the sum of treatment sizes in a single Rule must be 100.

Suggest Edits

Condition

 

A Condition consists of different Matchers. A customer satisfies a Condition only of it satisfies all the Matchers.

{
  “combiner”: "AND",
  “matchers”: [ Matcher ]
}

Note that when configuring or updating a `Split Definition, there is no need to specify the combiner, since for now, Split only allows AND combiner.

Suggest Edits

Bucket

 

A bucket represents a sticky distribution of customers into treatments of a Split.

{
  “treatment”: String,
  “size”: Number
}
Suggest Edits

Matcher

 

A Matcher represents the logic for selecting a specific subset of your customer population. 

{
  “negate”: Boolean,
  “type”: MatcherType,
  “attribute”: String,
  "string": String,
  "bool" : Boolean,
  "strings" : [ String ],
  "number" : Number,
  "date" : Number,
  "between": { "from" : Number, "to" : Number },
  "depends": { "splitName": String, "treatment": String }
}

Note that depending on the type, different fields are required. All the rest of the fields do not need to be set.

Suggest Edits

Matcher Type

 

Split supports the following Matcher Types.

{
  IN_SEGMENT,
  
  EQUAL_SET,
  ANY_OF_SET,
  ALL_OF_SET,
  PART_OF_SET,

  ON_DATE,
  ON_OR_AFTER_DATE,
  ON_OR_BEFORE_DATE,
  BETWEEN_DATE,

  BOOLEAN,
  
  EQUAL_NUMBER,
  LESS_THAN_OR_EQUAL_NUMBER,
  GREATER_THAN_OR_EQUAL_NUMBER,
  BETWEEN_NUMBER,

  IN_LIST_STRING,
  STARTS_WITH_STRING,
  ENDS_WITH_STRING,
  CONTAINS_STRING,
  MATCHES_STRING,
  
  IN_SPLIT,
}

IN_SEGMENT

When using this type, the matcher selects the set of customers that fall within a Segment.

Fields

string: Mandatory.
negate: Optional.

EQUAL_SET

This matcher selects customers with a multi-valued attribute equal to a Set of provided String literals. Since this is a Set based matcher, the order of the Set does not matter.

Fields

strings: Mandatory.
attribute: Mandatory
negate: Optional.

ANY_OF_SET

This matcher selects customers with a multi-valued attribute containing any of a Set of provided String literals. Since this is a Set based matcher, the order of the Set does not matter.

Fields

strings: Mandatory.
attribute: Mandatory
negate: Optional.

ALL_OF_SET

This matcher selects customers with a multi-valued attribute containing every String literal in a provided Set. Since this is a Set based matcher, the order of the Set does not matter.

Fields

strings: Mandatory.
attribute: Mandatory
negate: Optional.

PART_OF_SET

This matcher selects customers with a multi-valued attribute that is a subset of a Set of values. Since this is a Set based matcher, the order of the Set does not matter.

Fields

strings: Mandatory.
attribute: Mandatory
negate: Optional.

ON_DATE

The ‘is on’ matcher is helpful for doing date equalities. Note that this matcher drops the time component of a DateTime when doing the comparison. Thus, the values 1457382451 and 1457382452 fall on the same date even though they represent different times.

Fields

date: Mandatory. Milliseconds since epoch.
attribute: Mandatory
negate: Optional.

ON_OR_AFTER_DATE

The ‘on or after date’ matcher is helpful for targeting customers that performed an action after a given time. As an example, you can use this matcher to target customers that registered or bought something after a certain time.

Note that this matcher ignores time fields smaller than minutes. Specifically; seconds, milliseconds, and nanoseconds are ignored when doing the comparison. In other words, you can compare dates down to the minute field.

Thus, the values 1457382451 and 1457382471 will be equal to one another, even though they represent different seconds.

Fields

date: Mandatory. Milliseconds since epoch.
attribute: Mandatory
negate: Optional.

ON_OR_BEFORE_DATE

The ‘on or before date’ matcher is helpful for targeting customers that performed an action before a given time. As an example, you can use this matcher to target customers that registered or bought something before a certain time.

Note that this matcher ignores time fields smaller than minutes. Specifically; seconds, milliseconds, and nanoseconds are ignored when doing the comparison. In other words, you can compare dates down to the minute field.

Thus, the values 1457382451 and 1457382471 will be equal to one another, even though they represent different seconds.

Fields

date: Mandatory. Milliseconds since epoch.
attribute: Mandatory
negate: Optional.

BETWEEN_DATE

This matcher is an AND between ON_OR_AFTER_DATE and ON_OR_BEFORE_DATE. The same rules of ignoring time fields smaller than seconds apply.

Fields

between: Mandatory. It is an object that contains two fields, from and to. Both fields
are dates represented by milliseconds since epoch.
attribute: Mandatory
negate: Optional.

BOOLEAN

This is a self-explanatory matcher. At least, we think so :-).

Fields

bool: Mandatory.
attribute: Mandatory

EQUAL_NUMBER

This matcher selects the subset of customers that have an attribute equal to a numeric value.

Fields

number: Mandatory.
attribute: Mandatory
negate: Optional.

LESS_THAN_OR_EQUAL_NUMBER

This matcher selects the subset of customers that have an attribute that is less than or equal to a numeric value.

Fields

number: Mandatory.
attribute: Mandatory
negate: Optional.

GREATER_THAN_OR_EQUAL_NUMBER

This matcher selects the subset of customers that have an attribute that is greater than or equal to a numeric value.

Fields

number: Mandatory.
attribute: Mandatory
negate: Optional.

BETWEEN_NUMBER

A matcher of this type will match if the received number is between the two ones specified.

Fields

between: Mandatory. It is an object that contains two fields, from and to.
attribute: Mandatory
negate: Optional.

IN_LIST_STRING

This matcher selects customers with an attribute or key that falls within a whitelist. The whitelist is encoded within the strings field. This matcher is case sensitive.

Fields

strings: Mandatory.
attribute: Optional. If it is set the match will be triggered against the attribute. If it is not set, the match will be against the key provided.
negate: Optional.

STARTS_WITH_STRING

This matcher selects customers with an attribute or key starting with any of a list of strings. This matcher is case sensitive. Note that the strings should not be regex patterns, they are string literals that are used for exact prefix matching.

Fields

strings: Mandatory.
attribute: Optional. If it is set the match will be triggered against the attribute. If it is not set, the match will be against the key provided.
negate: Optional.

ENDS_WITH_STRING

This matcher selects customers with an attribute or key ending with any of a list of strings. This matcher is case sensitive. Note that the strings should not be regex patterns, they are string literals that are used for exact suffix matching.

Fields

strings: Mandatory.
attribute: Optional. If it is set the match will be triggered against the attribute. If it is not set, the match will be against the key provided.
negate: Optional.

CONTAINS_STRING

This matcher selects customers with an attribute or key containing any of a list of strings. This matcher is case sensitive. Note that the strings should not be regex patterns, they are string literals that are used for exact contains matching.

Fields

strings: Mandatory.
attribute: Optional. If it is set the match will be triggered against the attribute. If it is not set, the match will be against the key provided.
negate: Optional.

MATCHES_STRING

This matcher selects customers with an attribute or key that matches the regex pattern in string.

Fields

string: Mandatory.
attribute: Optional. If it is set the match will be triggered against the attribute. If it is not set, the match will be against the key provided.
negate: Optional.

IN_SPLIT

This matcher is useful when you want to consider the experience of a customer for one Split in deciding the experience for the same customer for another Split. As an example, consider a team working on a brand new homepage and another team responsible for a new widget design on that new homepage. The Split controlling the widget should take into account whether or not the new homepage is turned on for a user.

Fields

depends: Mandatory. This object contains two fields, splitName and treatment.
attribute: Optional. If it is set the match will be triggered against the attribute. If it is not set, the match will be against the key provided.
negate: Optional.

Suggest Edits

Default Rule

 

The Default Rule is simply a list of buckets.
If a specific id did not match any Rule, then this rule is applied in order to determine the treatment to be returned.

Note that you do not need to provide all treatments in the Default Rule, however, the sum of treatment sizes must be 100

{
  "rules" : [{ "..." }],
  "defaultRule": [ 
    { "treatment": "on", size: 90 },
    { "treatment": "off", size: 10 } 
  ]
}

If no rule is matched for the id, then the Default Rule is evaluated and there is a 90% chance that the result will be on, and 10% chance that it will be off.

Suggest Edits

Create Split

Create a Split in your organization given a traffic type. This API does not configure the Split in any environment.

 
posthttps://api.split.io/internal/api/v2/splits/ws/wsId/trafficTypes/traffic_type_id_or_name
curl -v -X POST -d '{"name":"paywall_beta","description":"description"}' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/trafficTypes/user
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "paywall_beta",
    "description": "description",
    "trafficType": {
        "id": "8814ada0-8f4d-11e7-b345-124259445f48",
        "name": "user"
    },
    "creationTime": 1504300758457,
}
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error creating splitmetadata with traffic type user",
    "transactionId": "9ohnm6fexz"
}
{
    "code": 404,
    "message": "Could not find traffic type user",
    "transactionId": "9ohocva33h"
}
{
    "code": 409,
    "message": "SplitMetadata already exists paywall_beta",
    "transactionId": "9ohptmhsi8"
}

Path Params

traffic_type_id_or_name
string
required

The id or case sensitive name of the traffic type used to create the split

wsId
string
required

The id of the workspace used to create the split

Form Data

split
json

JSON object that contains the name and description of the Split.

 

JSON Payload Posted 

{
 "name": String, // Mandatory
 "description": String // Optional
}
 
var splitName = "TestSplit";
var trafficType = "user";
var description = "test description";
var newSplit = client.Splits().Create(splitName, trafficType, description);
Suggest Edits

List Splits

Retrieves the Splits for an organization.

 
gethttps://api.split.io/internal/api/v2/splits/ws/wsId/
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/{wsId}
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits?tag=foo
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits?tag=foo&tag=bar
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "objects": [
        {
            "name": "sample_feature",
            "description": "A sample feature to help you learn how split works.",
            "trafficType": {
                "id": "6414eaa0-8f4d-11e7-b345-124259445f48",
                "name": "user"
            },
            "creationTime": 1504294821336,
            "tags" : [{ "name": "one tag" }]
        }
    ],
  ...
    "offset": 0,
    "limit": 20,
    "totalCount": N
}
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error listing splitmetadatas",
    "transactionId": "9ohbr8wmzf"
}

Path Params

wsId
string
required

The id of the workspace that you want a list of splits from

Query Params

offset
int32

The offset to retrieve. Useful for pagination

limit
string

The maximum split metadatas to return per call. Max=50.

tag
string

repeatable tag parameter(s) to query by

 

JSON Received 

{
    "objects": [ SPLIT ], // Array of Splits returned
    "offset": Number, // Offset received
    "limit": Number, // Limit received
    "totalCount": Number // Total number of Splits
}
Suggest Edits

Get Split

Retrieves the Split.

 
gethttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/<SPLIT_NAME>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "paywall_beta",
    "description": "A sample feature to help you learn how split works.",
    "trafficType": {
        "id": "6414cea0-8f4d-11e7-b345-124259445f48",
        "name": "user"
    },
    "creationTime": 1504294821336,
    "tags" : [{ "name": "one tag" }]
}
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error getting splitmetadata paywall_beta",
    "transactionId": "9oh3698lve"
}
{
    "code": 404,
    "message": "Could not find splitmetadata paywall_beta",
    "transactionId": "9oh3lpt0d0"
}

Path Params

split_name
string
required

The case sensitive name of the Split that will be retrieved

wsId
string
required

The id of the workspace used to create the split

 

JSON Received 

{
    "name": String,
    "description": String, 
    "trafficType": URN, // Containing id and name of the Traffic Type
    "creationTime": Number // Milliseconds since epoch
}
Suggest Edits

Delete Split

Delete a Split from your organization. This will automatically unconfigure the Split Definition from all environments. An SDK calling this Split will return "control".

 
deletehttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name
curl -v -X DELETE \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/<SPLIT_NAME>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
true
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error deleting splitmetadata paywall_beta",
    "transactionId": "9oh5ar3mhy"
}
{
    "code": 404,
    "message": "Could not find splitmetadata paywall_beta",
    "transactionId": "9oh5po4izh"
}

Path Params

split_name
string
required

The case sensitive name of the Split that will be deleted you want to kill

wsId
string
required

The id of the workspace for the split you want to delete

 
Suggest Edits

Update Split Description

Changes the description of a particular Split.

 
puthttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name/updateDescription
curl -v -X PUT -d 'the new description' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/<SPLIT_NAME>/updateDescription
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "paywall_beta",
    "description": "the new description",
    "trafficType": {
        "id": "8814ada0-8f4d-11e7-b345-124259445f48",
        "name": "user"
    },
    "creationTime": 1504300758457
}
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error updating description of splitmetadata paywall_beta",
    "transactionId": "9ohnm6fexz"
}

Path Params

split_name
string
required

The case sensitive name of the Split that will updated.

wsId
string
required

The id of the workspace for the split you want to edit

Form Data

description
json

JSON Object with the description

 
Suggest Edits

Create Split Definition in Environment

Configures a Split Definition for a specific environment.

 
posthttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name/environments/environment_id_or_name
curl -v -X POST \
  -d '{"treatments":[{"name":"on"},{"name":"off"}],"defaultTreatment":"off","rules":[{"buckets":[{"treatment":"on","size":50},{"treatment":"off","size":50}],"condition":{"matchers":[{"type":"IN_SEGMENT","string":"employees"}]}}],"defaultRule":[{"treatment":"off","size":100}]}' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/<SPLIT_NAME>/environments/<ENVIRONMENT_NAME_OR_ID>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
      "name":"paywall_beta",
      "environment": { "type":"Environment", "id": "dde603a0-30f1-11e7-ba78-12395d4a9634","name":"Production" },
      "trafficType": { "type":"TRAFFIC_TYPE", "id": "4d3405a0-9ca5-11e5-9706-16a11fb02dec","name":"user" },
      "killed":false,
      "treatments":[{"name":"on"},{"name":"off"}],
      "defaultTreatment":"off",
      "trafficAllocation":100,
      "rules": [
            {
                  "buckets":[{"treatment":"on","size":50},{"treatment":"off","size":50}],
                  "condition": {
                      "combiner": "AND",
                      "matchers": [
                          {"type":"IN_SEGMENT","string":"employees"}
                      ]
                  }
            } 
      ],
      "defaultRule": [ {"treatment":"off","size":100} ],
      "creationTime":1508522181447,
      "lastUpdateTime":1508522181447
}

{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error creating splitmetadata with traffic type user",
    "transactionId": "9ohnm6fexz"
}
{
    "code": 404,
    "message": "Could not find traffic type user",
    "transactionId": "9ohocva33h"
}
{
    "code": 409,
    "message": "SplitMetadata already exists paywall_beta",
    "transactionId": "9ohptmhsi8"
}
{
    "code": 404,
    "message": "Could not find splitmetadata paywall_beta",
    "transactionId": "9ty4h6w63k"
}

Path Params

environment_id_or_name
string
required

The id or case sensitive name of the environment in which you want to create the split

split_name
string
required

The case sensitive name of the Split that will be configured

wsId
string
required

the id of the workspace you want to create a split definition in

Form Data

split
json

JSON object that contains the split

 

JSON Payload 

{
  "treatments": [ Treatment ], // Mandatory
  "defaultTreatment": String, // Mandatory
  "rules": [ Rule ], // Optional
  "defaultRule": [ Bucket ] // Mandatory
}

Detailed information of the payload structure can be found on Split Grammar.

Suggest Edits

Get Split Definition in Environment

Retrieves a Split Definition given the name and the environment.

 
gethttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name/environments/environment_id_or_name
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/<SPLIT_NAME>/environments/<ENVIRONMENT_NAME_OR_ID>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "paywall_beta",
    "environment": {
        "id": "2626cf50-73d7-11e7-91fb-0ec612a5b38a",
        "name": "Production"
    },
		"trafficType": { 
      	"id": "4d3405a0-9ca5-11e5-9706-16a11fb02dec",
      	"name":"user"
    },
    "killed": false,
    "treatments": [ { "name": "on" }, { "name" : "off" } ],
    "defaultTreatment": "off",
    "trafficAllocation": 100,
    "rules": [
        {
            "buckets": [ 
                { "treatment" : "on", "size": 50 }, { "treatment": "off", "size": 50 } 
            ],
            "condition": {
                "combiner":"AND",
                "matchers": [ { "type": "IN_SEGMENT", "string": "employees" } ]
            }
        } 
    ],
    "defaultRule": [ { "treatment": "off", "size": 100 } ],
    "creationTime": 1508790002232,
    "lastUpdateTime": 1508790002232
}
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error getting split paywall_beta for environment Production",
    "transactionId": "9odlgm8gcl"
}
{
    "code": 404,
    "message": "Could not find ...",
    "transactionId": "9oel68tyhp"
}

Path Params

environment_id_or_name
string
required

The id or case sensitive name of the environment in which you want get the split

split_name
string
required

The case sensitive name of the Split that will be retrieved

wsId
string
required

the id of the workspace you want to get a split definition from

 

JSON Received 

{
    "name": String,
    "environment": URN, // Containing id and name of the environment
    "killed": Boolean,
    "treatments": [ Treatment ],
    "defaultTreatment": String,
    "trafficAllocation": Number, // Between 0 and 100
    "rules": [ Rule ],
    "creationTime": Number, // Milliseconds since epoch
    "lastUpdateTime": Number // Milliseconds since epoch
}

Detailed information of the payload structure can be found on Split Grammar.

Suggest Edits

Partial Update Split Definition in Environment

Updates a Split Definition for a specific environment.

 
patchhttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name/environments/environment_id_or_name
curl -v -X PATCH \
  -d '[{"op": "replace", "path": "/trafficAllocation", "value":50}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/paywall_beta/environments/Production
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "paywall_beta",
    "trafficAllocation": 50,
    ...
}

{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error deleting split test for environment Production",
    "transactionId": "9of55hrmyp"
}
{
    "code": 404,
    "message": "Could not find split paywall_beta for environment Production",
    "transactionId": "9oezqemsif"
}
{
    "code": 400,
    "message": "Failed to update paywall_beta on environment Production",
    "transactionId": "9ty4h6w63k"
}

Path Params

environment_id_or_name
string
required

The id or case sensitive name of the environment in which you want get the split

split_name
string
required

The case sensitive name of the Split that will be updated

wsId
string
required

the workspace of the id you want to update a split definition in

Form Data

update_split
json

JSON object that contains the attributes of a split to be updated in JsonPatch format

 

This API call allows to update any field of a split using JsonPatch.

A few examples below.

Kill / Restore a Split

curl -v -X PATCH \
  -d '[{"op": "replace", "path": "/killed", "value": true}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

The example above will kill a Split for a particular environment.

Change Traffic Allocation

curl -v -X PATCH \
  -d '[{"op": "replace", "path": "/trafficAllocation", "value":50}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

The example above will change the traffic allocation to 50.

Change Default Treatment

curl -v -X PATCH \
  -d '[{"op": "replace", "path": "/defaultTreatment", "value": "on"}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

The example above will set the default treatment to "on".

Add a Key (i.e user) to a treatment whitelist with no keys

The following example will add the key "3" as the first key in the whitelist of the first treatment.

curl -v -X PATCH \
  -d '[{"op": "add", "path": "/treatments/0/keys", "value": ["3"]}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

Add a Key (i.e user) to a treatment whitelist with existing keys

The following example will add the key "4" to the whitelist for the first treatment, given that a treatment that already has one or more keys.

curl -v -X PATCH \
  -d '[{"op": "add", "path": "/treatments/0/keys/-", "value": "4"}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

Remove a Key (i.e user) from a treatment whitelist

curl -v -X PATCH \
  -d '[{"op": "remove", "path": "/treatments/0/keys/2"}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

The example above will remove the third element of the whitelist for the first treatment.

Replace a Key (i.e user) in a treatment whitelist

curl -v -X PATCH \
  -d '[{"op": "replace", "path": "/treatments/0/keys/0", "value": "7"}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

The example above replaces the first element of the whitelist for the first treatment and sets it to "7".

Add a Segment (i.e employees) to a treatment whitelist

Given a treatment that already has a segment in the whitelist.

curl -v -X PATCH \
  -d '[{"op": "add", "path": "/treatments/1/segments/-", "value": "beta"}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

The example above will add the segment "beta" to the second treatment.

Remove a Segment (i.e employees) from a treatment whitelist

curl -v -X PATCH \
  -d '[{"op": "remove", "path": "/treatments/0/segments/1"}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

The example above will remove the second segment from the whitelist for the first treatment.

Rename a Treatment

Given the Split definition,

{
 "...",
 "treatments" :[{ "name":"on" }, {"name":"off" } ],
 "rules" :[
  {
   "...",
   "buckets": [
    { "treatment":"on","size":80 },
    { "treatment":"off","size":20 }
   ]
  }
 ],
 "defaultRule": [
   { "treatment":"on", "size": 50 },
   { "treatment":"off", "size": 50}
 ],
 "..."
}

To rename "on" to "first_version",

curl -v -X PATCH \
  -d '[{ "op": "replace", "path": "/rules/0/buckets/0/treatment", "value": "first_version" }, { "op": "replace", "path": "/treatments/0/name", "value": "first_version" }, { "op": "replace", "path": "/defaultRule/0/treatment", "value": "first_version" }]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

Add a Rule

Given the Split Definition,

{
 "...",
 "treatments" :[{ "name":"on" }, {"name":"off" } ],
 "rules" :[{"..."}],
 "defaultRule": [
   { "treatment":"on", "size": 50 },
   { "treatment":"off", "size": 50}
 ],
 "..."
}

To add a rule,

curl -v -X PATCH \
  -d '[{"op": "add", "path": "/rules/0", "value": {"buckets":[{"treatment":"on","size":50},{"treatment":"off","size":50}],"condition":{"matchers":[{"type":"IN_SEGMENT","string":"employees"}]}}}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

The example above will add the "In Segment" rule as the first rule of the Split.

Remove a Rule

curl -v -X PATCH \
  -d '[{"op": "remove", "path": "/rules/1"}]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/paywall_beta/environments/Production

The example above will remove the second rule of the Split.

Suggest Edits

Full Update Split Definition in Environment

Performs a full update of a Split Definition for a specific environment.

 
puthttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name/environments/environment_id_or_name
curl -v -X PUT \
  -d '{"treatments":[{"name":"on","segments":["employees"]},{"name":"off","keys":["one","two"]}],"defaultTreatment":"on","trafficAllocation":80,"rules":[],"defaultRule":[{"treatment":"off","size":100}]}' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/<SPLIT_NAME>/environments/<ENVIRONMENT_NAME_OR_ID>

A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "paywall_beta",
    "trafficAllocation": 80,
    ...
}

{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error updating split test for environment Production",
    "transactionId": "9of55hrmyp"
}
{
    "code": 404,
    "message": "Could not find split paywall_beta for environment Production",
    "transactionId": "9oezqemsif"
}
{
    "code": 400,
    "message": "Failed to update paywall_beta on environment Production",
    "transactionId": "9ty4h6w63k"
}

Path Params

environment_id_or_name
string
required

The id or case sensitive name of the environment in which you want get the split

split_name
string
required

The case sensitive name of the Split that will be updated

wsId
string
required

The id of the workspace you want to update a split definition in

Form Data

split_definition
json

JSON object that contains the full split definition to be updated

 
Suggest Edits

Remove Split Definition from Environment

Unconfigures a Split Definition for a specific environment. Any SDK calling this split will return "control" for the selected environment.

 
deletehttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name/environments/environment_id_or_name
curl -v -X DELETE \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/<SPLIT_NAME>/environments/<ENVIRONMENT_NAME_OR_ID>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
true
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error deleting split paywall_beta for environment Production",
    "transactionId": "9of55hrmyp"
}
{
    "code": 404,
    "message": "Could not find split paywall_beta for environment Production",
    "details": null,
    "transactionId": "9oezqemsif"
}

Path Params

environment_id_or_name
string
required

The id or case sensitive name of the environment in which you want get the split

split_name
string
required

The case sensitive name of the Split that will be unconfigured

wsId
string
required

The id of the workspace you want to remove a split definition from

 
Suggest Edits

Lists Split Definitions in Environment

Retrieves the Split Definitions given an environment.

 
gethttps://api.split.io/internal/api/v2/splits/ws/wsId/environments/environment_id_or_name
curl -v -X GET \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/environments/<ENVIRONMENT_NAME_OR_ID>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "objects": [
        {
            "name": "paywall_beta",
            "environment": { ... },
          	"trafficType": { ... },
            "killed": false,
            "treatments": [ { ... } ],
            "defaultTreatment": "off",
            "trafficAllocation": 100,
            "rules": [ { ... } ],
            "creationTime": 1508261321997,
            "lastUpdateTime": 1508261321997        
        },
        { ... }
    ],
    "offset": 0,
    "limit": 20,
    "totalCount": N
}
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}
{
    "code": 401,
    "message": "Error listing splits for environment Production",
    "transactionId": "9ofcp0yvpb"
}
{
    "code": 404,
    "message": "Could not find environment Production",
    "transactionId": "9ofdd0bn9m"
}

Path Params

environment_id_or_name
string
required

The id or case sensitive name of the environment in which you want get the split

wsId
string
required

The id of the workspace you want to get split definitions from

Query Params

offset
int32

The offset to retrieve. Useful for pagination

limit
string

The maximum splits to return per call. Max=50.

 

JSON Received 

{
    "objects": [ SPLIT_DEFINITIONS ], // Array of Split Definitions returned
    "offset": Number, // Offset received
    "limit": Number, // Limit received
    "totalCount": Number // Total number of Split Definitions
}
Suggest Edits

Kill Split in Environment

Kill a feature in a specific environment

 
puthttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name/environments/environment_name_or_id/kill
curl -v -X PUT \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/<SPLIT_NAME>/environments/<ENVIRONMENT_NAME_OR_ID>/kill
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
// no object returned
// no object returned
{
  "code": 403,
  "message": "Failed to kill $split_name in $environment_id_or_name"
}
{
  "code": 500,
  "message": "Failed to kill $split_name in $environment_id_or_name"
}
{
  "code":400,
  "message":"Failed to kill name=$split_name, environment=$environment_id"
}

Path Params

environment_name_or_id
string
required

The id or case sensitive name of the environment in which you want to kill the feature

split_name
string
required

The case sensitive name of the split you want to kill

wsId
string
required

The id of the workspace you want to kill a split in

 
Suggest Edits

Restore Split in Environment

Restore a feature in a specific environment

 
puthttps://api.split.io/internal/api/v2/splits/ws/wsId/split_name/environments/environment_name_or_id/restore
curl -v -X PUT \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/splits/ws/<WORKSPACE_ID>/<SPLIT_NAME>/environments/<ENVIRONMENT_NAME_OR_ID>/restore
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
// no object returned
// no object returned
{
  "code": 403,
  "message": "Failed to kill $split_name in $environment_id_or_name"
}
{
  "code": 500,
  "message": "Failed to kill $split_name in $environment_id_or_name"
}
{
  "code":400,
  "message":"Failed to kill name=$split_name, environment=$environment_id"
}

Path Params

environment_name_or_id
string
required

The id or case sensitive name of the environment in which you want to restore the feature

split_name
string
required

The case sensitive name of the split you want to restore

wsId
string
required

The id of the workspace you want to restore a split in

 
Suggest Edits

Tags Overview

 
Suggest Edits

Associate Tags

 
posthttps://api.split.io/internal/api/v2/tags/object/object_name/objecttype/object_type
curl -v -X POST -d '["tagA," "tagB"]' \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v2/tags/object/{object_name}/objecttype/{object_type}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "objects": [
      	{
          	"name":"tagA",
          	"objectType": "Split",
          	"objectName": "SplitName,
        },
        { ... }
    ],
    "offset": 0,
    "limit": 20,
    "totalCount": N
}

Path Params

object_name
string
required
object_type
string
required

Object type to associate tags to. Currently supported: "Split"

Form Data

tags
json

String list. End state of tags assocated with the object

 
Suggest Edits

Events Overview

 

This API allows you to send events programmatically to Split. Record events that measure your customer behavior across your application including clicks, views, checkout events, page load times, or any event that measures your customer experience.

Metrics can then be calculated from these events to measure the results of experiments rolled out as Splits. Learn more about Creating a Metric in Split.

In the examples below you'll see that the payload can take up to six arguments. The proper data type and syntax for each are:

  • key: Represents the customer_id used in your getTreatment call and firing this track event.
    • Expected Data Type: String
  • trafficTypeName: Represents the traffic type of the customer id in the track call.
    • Expected Data Type: String
    • You can only pass values that match the names of Traffic Types that you have defined in your instance of Split.
  • eventTypeId: Represents the event type that this event should correspond to.
    • Expected Data Type: String
    • Full requirements on this argument are:
      • 80 characters or less
      • Starts with a letter or number
      • Contains only letters, numbers, hyphen, underscore, or period.
      • This is the regular expression we use to validate the value: [a-zA-Z0-9][-_\.a-zA-Z0-9]{0,62}
  • value: (optional) Represents the value to be used in creating the metric. This field can be sent in as null or 0 if you intend to purely utilize the count function when creating a metric.
    • Expected Data Type: Integer or Float
  • environmentName: Represents the environment in Split you want this event to be mapped to.
    • Expected Data Type: String
    • You can only pass values that match the names of Environments that you have defined in your instance of Split.
  • timestamp: (optional) Represents the time in milliseconds since epoch that the event occurred.
    • Expected Data Type: Integer
Suggest Edits

Create Event

 
posthttps://events.split.io/api/events
curl -X POST -H 'SplitSDKVersion: java-1.2.3' \
  -H 'SplitSDKMachineName: Work-Laptop' \ 
  -H 'SplitSDKMachineIP: 8.8.8.8' \ 
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer SDK_API_KEY' \
  -d \
'
{
	"eventTypeId": "page_load", 
  "environmentName": "Staging",      
  "trafficTypeName": "user", 
  "key": "key_user_0", 
  "timestamp": 1513357833000, 
  "value": 0.8 
}' \
 https://events.split.io/api/events
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
If the event is successfully sent to split.
When the header for the SDK_API_KEY is not present.
When the request has no body or the body does not have a valid structure.
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}

Body Params

event
json

Headers

SplitSDKVersion
string

This is your sdk and version appended with a '-' in between.

SplitSDKMachineName
string

The name of the machine issuing the request.

SplitSDKMachineIP
string

The IP address of the machine issuing the request

 
Suggest Edits

Create Events

 
posthttps://events.split.io/api/events/bulk
curl -X POST -H 'SplitSDKVersion: java-1.2.3' \
  -H 'SplitSDKMachineName: Work-Laptop' \ 
  -H 'SplitSDKMachineIP: 8.8.8.8' \ 
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer SDK_API_KEY' \
  -d \
'
[
{ 
 "eventTypeId": "page_latency", 
 "environmentName": "Staging",      
 "trafficTypeName": "user", 
 "key": "key_user1", 
 "timestamp": 1513357833000, 
 "value": 0.8  
}, 
{ 
 "eventTypeId": "page_load", 
 "environmentName": "Staging",      
 "trafficTypeName": "user", 
 "key": "key_user2", 
 "timestamp": 1513357834000, 
 "value": 0.9  
 }
 ]
 ' \
 https://events.split.io/api/events/bulk
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
When the header for the SDK_API_KEY is not present.
When the request has no body or the body does not have a valid structure.
{
    "code": 403,
    "message": "Organization does not have permissions to execute API",
    "transactionId": "9oek34hvot"
}

Body Params

event
json

Headers

SplitSDKVersion
string

This is your sdk and version appended with a '-' in between.

SplitSDKMachineName
string

The name of the machine issuing the request.

SplitSDKMachineIP
string

The IP address of the machine issuing the request