The Segment Public API supports alpha, beta, and stable versions. Each version carries its own guarantees, trade-offs, and risks. Because customers can access all three API versions, you can use the version that best fits your organization's needs.

Segment doesn't lock you into a global API version. You can choose which endpoint version fits your needs and which trade-offs you prefer.

The following table offers an overview of each version:

Version Overview
- Fairly unstable
- Basic documentation
- Breaking changes are common and expected
- Strict rate limits
- Use at your own risk
- Fairly stable
- Basic documentation with examples and corner cases
- Breaking changes are possible
- Flexible rate limits
- Should be safe for non-critical workflows
- Highest level of stability
- Comprehensive documentation that includes examples, corner cases, and limitations
- No breaking changes expected*
- Standard rate limits
- Safe to use for critical workflows

Accessing versions

Each available endpoint is tagged with its corresponding supported versions so that you can choose the API version that best supports your use case.

Standard API calls

Standard API call requests are forwarded to the endpoint's most stable available version.

The Segment Public API first checks for an endpoint's stable version, then falls back to a beta version, if one exists. If no mature API versions are available, Segment falls back to an alpha version.

Versioned API calls

You can pass in the specific version of the API call you want to access as an HTTP header. Do this when you want to access API features currently unavailable on the stable version.

The following example shows a correctly formatted request to the alpha version of the sources route:

curl \
  --request GET
  --url '' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Accept: application/vnd.segment.alpha+json'

The next example shows the same request made to the same endpoint's beta version.

curl \
  --request GET
  --url '' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Accept: application/vnd.segment.beta+json'

Backwards-incompatible or breaking changes

New endpoint versions become available when Segment makes new, backwards-incompatible ("breaking") changes to the Segment Public API. Segment reserves the right to make breaking changes to the API, though such changes will occur infrequently. To minimize disruption to your workflow, Segment adds special release versions to new, backwards-incompatible routes.