Config API

The Config API enables you to programmatically manage Segment workspaces, sources, destinations and more. With the API you can:

  • List all your workspace Sources and Destinations to see how data flows through Segment
  • Create new Destinations - or delete them - with a few lines of code
  • Configure, disable, or view Sources and manage connected Destinations
  • Get a complete view of all the Sources and Destinations available in Segment’s catalog
  • Configure a Tracking Plan to see how data conforms to your expected schema

The Config API is a set of REST services under segmentapis.com:

ServiceDescription
Access TokensManage access tokens
Source CatalogGet info about all event and cloud sources
Destination CatalogGet info about all destinations
WorkspacesGet info about workspaces
SourcesManage workspace sources
DestinationsManage workspace destinations
Tracking PlansManage workspace tracking plans

To see all the API methods and models see the Segment Config API Reference.

At this time there are no language-specific clients. However the API Reference also contains example code snippets for cURL, Go, Node, Python and more.

Quick Start

You can interact with the API from the command line. First install the curl tool.

$ brew install curl

Personal Access Tokens

You can use the Config API with a personal access token to programmatically access Segment resources that you own. Personal access tokens are created by, and belong to individual Segment users, and can only access resources that user owns.

These are currently only suitable for first party, trusted applications, such as your personal local scripts and server side programs. Partners should not prompt Segment users for their username and password and save a personal access token as a way to delegate access. See the Authentication doc for more information.

When you create an access token, you’ll give it a description, a workspace, and determine whether it has full or read-only access:

$ USER=me@example.com
$ PASS=<your Segment password>
$ WORKSPACE=<your Segment workspace>

$ curl \
  -X POST \
  -d "{'access_token': {'description': 'my access token', 'scopes': 'workspace', 'workspace_names': ['workspaces/$WORKSPACE']}}" \
  -u "$USER:$PASS" \
  https://platform.segmentapis.com/v1beta/access-tokens

Example response:

{
  "name": "access-tokens/5",
  "description": "my access token",
  "scopes": "workspace",
  "create_time": "2018-10-12T22:36:39Z",
  "token": "qiTgISif4zprgBb_5j4hXfp3qhDbxrntWwwOaHgAMr8.gg9ok4Bk7sWlP67rFyXeH3ABBsXyWqNuoXbXZPv1y2g",
  "workspace_names": [
    "workspaces/myworkspace"
  ]
}

Warning: Secret Token

Note that you can not retrive the plain-text token later, so you should save it in a secret manager. If you lose the token you can generate a new one.

API Requests

Now that you have a personal access token, you can use this token to access the rest of the Config API by setting it in the Authorization header of your requests, for example:

$ ACCESS_TOKEN=qiTgISif4zprgBb_5j4hXfp3qhDbxrntWwwOaHgAMr8.gg9ok4Bk7sWlP67rFyXeH3ABBsXyWqNuoXbXZPv1y2g

$ curl \
  -X GET \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://platform.segmentapis.com/v1beta/workspaces

Example response:

{
  "workspaces": [
    {
      "name": "workspaces/myworkspace",
      "display_name": "My Space",
      "id": "e5bdb0902b",
      "create_time": "2018-08-08T13:24:02.651Z"
    }
  ],
  "next_page_token": ""
}

Reference

For an overview of the API’s common design patterns and important information about versioning and compatibility, see the API Design document.

To see all the API methods and models see the Segment Config API Reference.


If you have any questions, or see anywhere we can improve our documentation, please let us know!