The most interesting API RudderStack has on the catalog is the smallest one that matters: the RudderStack HTTP API. It has 7 operations, every one a POST, and it is the front door for every event the rest of the platform routes, transforms, warehouses and syncs back out. RudderStack scores 77.0, exemplar, with an Agent Readiness of 57.2. This contract is a large part of why that score is not higher.
The catalog lists 13 API pages for RudderStack. Only two of them have a contract with operations: this one with 7 and the Internal API with 5. That makes 12 operations in total. The other eleven pages describe real products, including Config Backend, Tracking Plan, Transformations, Reverse ETL and Profiles, but none of them has a machine-readable contract we hold.
The seven operations
| Operation | Path | What it records |
|---|---|---|
| Identify | /v1/identify |
a user and their traits |
| Track | /v1/track |
a named event with properties |
| Page | /v1/page |
a web page view |
| Screen | /v1/screen |
a mobile screen view |
| Group | /v1/group |
a user’s membership in an account |
| Alias | /v1/alias |
a merge of an old identity into a new one |
| Batch | /v1/batch |
any mix of the above in one call |
This is the Segment-style spec, implemented faithfully, and that is the point. An integrator who has written against one customer-data platform already knows this API. Authentication is HTTP Basic, with the source write key as the username. Every operation declares the same five responses: 200, 400, 401, 413 and 429. Declaring 413 and 429 on every operation is more honest than most ingestion contracts are about payload limits and throttling.
Where it breaks for an agent
The contract declares servers: - url: /v1, and its paths already begin with /v1/. Resolved literally, that gives /v1/v1/identify. The API page records the base as https://{dataPlaneUrl}, because each customer gets its own data plane. So there are two problems. A relative server is not callable, and when you prepend it the path is wrong. The record agrees: 0.0 percent of RudderStack’s contracts score as callable. The doubled prefix is already in the gateway contract we harvested, so it was not introduced by our split. We still published it without correcting it.
The second gap is idempotency. The Agent Readiness record has it dark, and the contract never mentions messageId, the field the Segment spec uses to deduplicate retries. An agent that gets a 429 and retries a Track call has nothing in this contract that tells it whether it just counted the purchase twice.
The phrasing on the API page, which pairs each operation with questions and instructions in plain language, was generated by API Evangelist. It is not RudderStack’s work and it is not credited to them.
Takeaway
RudderStack has the hard parts in place: a stable, widely understood event vocabulary and honest error codes. What would move the number is a contract with an absolute, templated server (https://{dataPlaneUrl}/v1 with the paths trimmed), a documented messageId deduplication guarantee, and published contracts for the eleven pages that have none. On our side, we should fix the doubled /v1 in our copy of the contract.
Read the API at apis.io/apis/rudderstack/rudderstack-http-api-api/ and RudderStack’s own docs at rudderstack.com/docs/api/http-api/.