Split docs

Suggest Edits

Introduction

 

This section details Split's admin 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 integrate Split with the tools your team uses.

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 by requiring an API key.

An Authorization header must be added containing your API for the request.

Authentication Header

To access the Split API, you must create a key with type admin. 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 APIs section of settings. 

Authorization: Bearer ADMIN_API_KEY

Learn more about API keys

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

Suggest Edits

Segments Overview

 

Split allows you to segment your customer base and use these segments in your release process.

Segments are groups of customers that can be used in feature splits. When viewing a particular segment, you can easily add, remove, or import customers via CSV or via API.

As you think about feature releases it’s good to take a step back and acknowledge all of the things that segmentation helps you do better. Your segments should be used to:

  • Ensure quality testing. (Example: you may want to release to your internal or outsourced QA team - create segment qa_team)
  • Target employees for internal testing. (Example: you may want to release to your entire company to test the feature or gather feedback - create segment employees)
  • Plan your release strategy. (Example: you may want to release to a group of customers who have expressed interest in a particular feature - create segment beta_tester)

These are just a few examples that engineering and product development teams should think about. There are a lot more ways that you can apply segmentation to drive better results and ensure a successful and safe release.

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

Bulk upload 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/v1/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/v1/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

Bulk upload 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/v1/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/v1/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

Retrieve segments keys for a given existing segment.

 
gethttps://api.split.io/internal/api/v1/segments/environment_id/segment_name/keys
curl -v -X GET \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/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

Delete Segment keys

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

 
puthttps://api.split.io/internal/api/v1/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/v1/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

 

Split lets you take a feature to production, but be targeted about which of your customers are exposed to that feature. Split lets you be as granular in your targeting as you want: you can target individual, segments or percentages of customers. This granular targeting is achieved by creating a 'Split' in the web console.

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

Kill Split

Kill a feature in a specific environmentntell

 
puthttps://api.split.io/internal/api/v1/splits/kill/environment_id_or_name/split_name
curl -v -X PUT \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer ADMIN_API_KEY' \
  https://api.split.io/internal/api/v1/splits/kill/Production/paywall_beta
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_id_or_name
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