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 |
|---|---|
alpha application/vnd.segment.alpha+json |
- Fairly unstable - Basic documentation - Breaking changes are common and expected - Strict rate limits - Use at your own risk |
beta application/vnd.segment.beta+json |
- Fairly stable - Basic documentation with examples and corner cases - Breaking changes are possible - Flexible rate limits - Should be safe for non-critical workflows |
stable application/vnd.segment.stable+json |
- 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 |
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 'https://api.segmentapis.com/sources' \
--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 'https://api.segmentapis.com/sources' \
--header "Authorization: Bearer $TOKEN" \
--header 'Accept: application/vnd.segment.beta+json'
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.