Getting Started

The Segment Public API requires that you have an authentication token before you send requests. This section explains how to get a token and add it to your requests.

1. Log in to the Segment App, and choose the Workspace you want to generate a token for. Each Segment Workspace requires a separate token.
2. Click Settings in the left menu to access Workspace Settings. Navigate to the Access Management tab, and click Tokens. This tab lists any existing tokens created for the Workspace.
3. Click +Create Token , and follow the prompts to generate a new token. Be sure to select a Public API token, and not a Config API token. Once generated, store the token somewhere safe, like a password store or other secrets manager.

The Segment Public API only accepts requests in the HTTP 1.1 or HTTP 2 protocols over port 443 (HTTPS). All communications must be encrypted, so requests on port 80 (plain HTTP) will be refused.

The Segment Public API can be accessed through multiple regions, depending on data residency policies: for US-based Workspaces, use api.segmentapis.com. For EU-based Workspaces, eu1.api.segmentapis.com.

You must send the token as an Authorization header in your requests. Use the following format: Authorization: Bearer $TOKEN, where $TOKEN is the variable containing the value of the token.

For example, in a US-based Workspace:

curl \
  --request GET \
  --url https://api.segmentapis.com/ \
  --header "Authorization: Bearer $TOKEN"

In an EU-based Workspace:

curl \
  --request GET \
  --url https://eu1.api.segmentapis.com/ \
  --header "Authorization: Bearer $TOKEN"

Learn more about how the Segment Public API handles authentication in the next section.

SDKs for the Public API are available in JavaScript/TypeScript, Go, Java, Python, C# and Swift. If you develop in one of these platforms, installing and using the SDK is a simpler way to call Public API.

JavaScript and TypeScript (Node.js)

To install the @segment/public-api-sdk-typescript package, you can use either npm or pnpm, depending on which package manager you prefer. Here are the installation instructions for each:

NPM

• Open a terminal window and navigate to the directory where you want to install the package.
• Run the following command:

npm install @segment/public-api-sdk-typescript

pnpm

• Open a terminal window and navigate to the directory where you want to install the package.
• Run the following command:

pnpm add @segment/public-api-sdk-typescript

After doing the above, the package should be installed and ready for use in your project.

Go

To install the segmentio/public-api-sdk-go package, you will need to have the Go programming language installed on your system. You can check if you have Go installed by running the following command in your terminal:

go version

If Go is installed, this command will print the version number. If Go is not installed, you can follow the instructions on the Go website to install it: https://golang.org/doc/install

Once you have Go installed, you can install the segmentio/public-api-sdk-go package using the go get command. Here are the installation instructions:

• Open a terminal window and navigate to the directory where you want to install the package.
• Run the following command:

go get github.com/segmentio/public-api-sdk-go

This will download the package and all of its dependencies to your system. After the installation is complete, you can import and use the package in your Go code.

Here is an example of how to import and use the package in a Go program:

import "github.com/segmentio/public-api-sdk-go"

Note: You may need to add the $GOPATH/bin directory to your $PATH environment variable in order to use the package in your Go code. You can do this by running the following command in your terminal:

export PATH=$PATH:$GOPATH/bin

After doing the above, the package should be installed and ready for use in your project.

Java

To install the public-api-sdk-java package, you will need to have the Java Development Kit (JDK) installed on your system. You can check if you have the JDK installed by running the following command in your terminal:

java -version

If the JDK is installed, this command will print the version number. If the JDK is not installed, you can follow the instructions on the Oracle website to install it: https://www.oracle.com/java/technologies/javase-downloads.html

Once you have the JDK installed, you can install the @segment/public-api-sdk-java package using your preferred build tool. Here are the installation instructions for three popular build tools: Maven and Gradle.

Maven

• Open a terminal window and navigate to the directory where you want to install the package.
• Create a new file called pom.xml in this directory with the following contents:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>my-project</artifactId>
  <version>1.0-SNAPSHOT</version>
  <dependencies>
    <dependency>
      <groupId>com.segment.publicapi</groupId>
      <artifactId>segment-publicapi</artifactId>
      <version>33.0.4</version>
    </dependency>
  </dependencies>
</project>

• Run the following command to download and install the package and its dependencies: mvn install.

Gradle

• Open a terminal window and navigate to the directory where you want to install the package.
• Create a new file called build.gradle, or edit the existing one, and make sure it contains the following declaration:

dependencies {
  implementation "com.segment.publicapi:segment-publicapi:33.0.4"
}

After doing the above, the package should be installed and ready for use in your project.

Swift

To install the Swift Public API SDK, you will need to add it as a dependency to your project. You can do this using Swift Package Manager.

First, open your project in Xcode and navigate to the Swift Packages tab. Click the + button to add a new package dependency. Enter the repository URL for public-api: https://github.com/segmentio/public-api-sdk-swift.git.

Next, select the version of the SDK that you want to use, and click Next. Xcode will automatically resolve the dependencies for your project, and you should now be able to use Public API in your code.

Alternatively, you can add the following entry to your Package.swift file directly:

.package(name: "PublicApi", url: "git@github.com:segmentio/public-api-sdk-swift.git", branch: "master")

To use Public API, you will need to import it at the top of your Swift file:

import PublicApi

After doing the above, the package should be installed and ready for use in your project.

C#

The C# SDK package can be installed via Nuget.

To add the Segment Public API C# package to your project, run - dotnet add package Segment.PublicApi

Additional documentation for usage of this API can be found in the README section of the Segment Public API Nuget package page.