Learn more about the benefits of the Segment Public API over Config API in the benefits section.
The Config API and Public API do not share common endpoints, but they are conceptually similar.
To begin migration, Segment recommends that you inspect the Config API endpoints you use, and find their counterparts in the Public API.
URL patterns
Existing Config API URLs will not work against Public API. Segment provides a new simplified format. Most of the URLs in Public API follow the format below:
VERB /object
VERB /object/id
VERB /object/id/nested-object
VERB /object/id/nested-object/id
Examples:
GET /sources
PUT /destinations/fP7qoQw2HTWt9WdMr718gn
GET /destinations/fP7qoQw2HTWt9WdMr718gn/subscriptions/aJCn6DQsTLw9aBTqd34uQf
Some exceptions exist, like GET /warehouses/{warehouseId}/connected-sources/{sourceId}/selective-syncs where items nest further, but those are rare.
Slugs vs IDs
The Config API uses slugs, like my-source or google-analytics to identify objects. The Public API uses IDs. IDs provide the following advantages:
- No guarantees or expectations of size, ordering, collation or format to these IDs
- Once an object receives an ID, it will not change during the lifespan of that object
- No objects will ever share an ID, even over time
The Public API implies workspace IDs
The Public API scopes all operations to a Workspace. The Workspace ID itself is not passed into the requests, but Segment looks it up as a result of authorizing the request.
The Public API removes fields like parent and workspace, which exist in Config API endpoints, as they are no longer needed.
Enum values
Segment made all enumerated values in Public API use SCREAMING_UNDERSCORE casing across the board. No more guessing whether a field should have the value likeThis , LikeThis, like-this, like_this, etc. They’re all formatted the same in both inputs and outputs now.
Rate limits
There is a completely new rate limiting system in place in Public API. Please refer to Rate Limits to learn more.
Object limits
Some objects (like Sources) are subject to limits depending on the Workspace type you use (team, business, etc). These limits are not different between Config API and Public API.
Endpoints operating on collections of items are generally limited to 200 items per call, unless otherwise noted in their documentation.
Payload size limits
Customers often ask about size limits for some endpoints, like Create Tracking Plan and Update Function. Segment may split these endpoints into multiple smaller / batchable operations so request sizes are not an issue, but in the meantime the Public API caps:
- Tracking Plan endpoints at about 2mb requests
- Functions endpoints at about 25mb requests
To learn more, please refer to Payload limits.