Conventions

What holds across every route: how the API is versioned, how it fails, how lists are paged, how to retry a write safely, and how to behave when you are asked to slow down. Write one error handler and one retry policy against this page and they apply everywhere.

Versioning

The version is part of the address (/api/public/v1) and is sent back on every response, errors included, as a header:

X-Tstr-Api-Version: v1

The one exception is a response stopped before it reaches the API (see Authentication): the API did not send it, so it cannot carry the header.

Within v1, changes are additive only. We may add:

• routes;
• optional request fields and parameters;
• fields in a response;
• values in a documented set, such as a new integration status;
• error types;
• scopes.

We do not remove or rename a route, a field, a scope or an error type, change a field's type or meaning, make an optional request field required, or start refusing a request that used to be accepted. A change that cannot be made that way would be a new version, served under its own prefix.

What that asks of your client:

• Ignore response fields you do not know. Do not reject a body for an extra key, and do not generate a strict schema that forbids one.
• Tolerate a value you do not know in a field that holds one of a set, and do not crash on it.
• Handle an error type you do not know by its HTTP status. See Error types.
• Do not depend on key order or on the spacing of a response.

Requests and responses

• Bodies are JSON. Timestamps are ISO 8601 in UTC with an explicit offset, such as 2026-10-16T09:30:00.123456+00:00.
• Credentials go in the Authorization: Bearer header only. See Authentication.
• Only the methods a route lists are served. A wrong method on a real path is a 404 unknown_route, not a 405, and HEAD and OPTIONS are not served: use GET. A trailing slash is a different path, and /meta/ is not /meta.
• To send PATCH, PUT or DELETE through a network that blocks them, see Authentication.
• The API is for servers and command-line tools. It does not send the cross-origin headers that would let browser JavaScript served from another site call it, and a preflight request from another origin is refused. Calling it from a page on another site will not work.

Errors

Every error from the API has one shape, whichever part of the API produced it. It is modelled on RFC 7807 problem details:

{
  "type": "insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "The access token does not carry every scope this operation needs. The WWW-Authenticate header lists all of them; re-authorize requesting that complete set."
}

• type is a stable machine-readable slug. This is the field to switch on. It is a slug, not a URL: there is nothing at the other end of it to fetch.
• status repeats the HTTP status code.
• title and detail are for a person reading a log, and are written to say who has to act. Their wording may change, so do not match on them.
• A 422 also has errors, a list with one entry for each problem. Each has loc (where in the request), msg and type. There is no field that echoes back what you sent.

The body's Content-Type is application/json, not application/problem+json. A 401, and the 403 for a missing scope, also carry a WWW-Authenticate: Bearer challenge whose resource_metadata parameter is the address of the protected-resource metadata.

An unexpected failure inside the API has this shape too: a 500 with type internal_error, and the version header. It says nothing about the cause, on purpose, so there is nothing in it to act on beyond retrying. A 5xx that does not follow this format usually came from something in front of the API and not from the API itself, so treat a 5xx you cannot parse as transient.

Error types

This is the complete list of types the API can return. A client should handle each by what it asks of whoever has to act. The status and the "who" are what differ.

The four governance refusals (grant_pending_approval, grant_denied, third_party_access_admins_only and third_party_access_disabled) are four different next actions, which is why they are four types. None is a 401: the token is genuine, and signing in again cannot change what the customer has decided. They are the customer's access policy at work, described from the administrator's side in Connected applications.

Types that are not in the table. The table holds every type this API's own code chooses, a route's own included, and the route reference says which routes return which. Some errors come from the web framework and not from a route, and carry a generic type of the form http_<status> (for example http_404), with the standard phrase for the status as the title. Types may be added within v1, as the versioning section says, so a client needs a default for any type it does not know: act on the status.

Pagination

Routes that return many records page with a keyset cursor. There is no offset and no page number: a long walk over records that are changing would skip some and repeat others, and the cursor carries on from the last record you saw instead.

A page looks like this:

{
  "items": [ "..." ],
  "next_cursor": "an-opaque-string",
  "count": 100
}

• Ask for the next page by sending next_cursor back as the cursor query parameter. next_cursor is null on the last page.
• count is the number of items on this page, not a total.
• A cursor is opaque. Do not build one, read one, or change one, and do not assume its format.
• A cursor this API did not send is refused with a 422. It is never read as "start from the beginning".

Each list route in the route reference says which parameters it takes. A short, complete listing, such as GET /integrations, is not paged.

Idempotency

Routes that create or change data take an Idempotency-Key header, so that a request repeated after a timeout or a dropped connection is not carried out twice.

• Send a fresh value (a UUID will do) for each logical operation, and send the same value again if you retry that operation. A key is 1 to 255 characters and not only spaces; anything else is 400 invalid_idempotency_key.
• If the key and the body match a request that has already completed, you get the original response back, with the original status, and nothing is done a second time. A retried POST /contacts is answered 201 with the contact it made, and not 409 for an address it has itself just taken.
• The same key with a different body is a 409 of type idempotency_key_reused: it is a mistake, not a retry. Change the request or the key.
• A request whose twin is still running is refused at once with a 409 of type idempotency_request_in_progress, and has done nothing. That one is not a mistake: it is the opposite instruction. Wait the number of seconds in Retry-After and send the same request again. If you are told again, wait again. A client that handles both 409s the same way will either give up on a request that was fine or repeat one that was wrong, which is why they are two types.
• A request that fails is not remembered, so repeating it runs it. A 5xx that you cannot tell took effect or not is exactly what the key is for: repeat it with the same key.
• The key belongs to the application, the person who authorized it, the method and the whole URL with its query string. The same value sent to two different contacts' URLs is two requests, and the same value from two applications is two requests. It does not belong to the access token, so a token refreshed between a request and its retry still finds the first answer.
• A key protects a retry, so the answer is remembered for seven days. It is not a way to guard against running the same job again later; that is what the re-run rules of the route are for.

Each route in the route reference says whether it accepts the header. It is required on POST /contacts:bulk and optional on the other writes.

Rate limits

When you go over a limit, the answer is 429 Too Many Requests with type: rate_limited and a Retry-After header: the number of seconds to wait. Wait at least that long before you send the request again, and if you keep being limited, slow down and back off further. It is not a problem with your credential, so do not sign in again, and a 429 carries no WWW-Authenticate challenge.

There are two limits, and both answer in the same way:

• Per application. Each application has an allowance of its own with each customer, shared by every process and every person using that application for that customer, wherever it runs. An application that works with several customers is limited at each one separately. This is the limit an integration is meant to meet first, if it meets one at all.
• Per network address. Each address that calls a customer's API also has an allowance there, counted before the access token is looked at. It is what keeps a flood of invalid credentials from costing the sign-in service a lookup apiece, and it is set well above the per-application limit, so an application that stays inside its own allowance does not meet it. Applications that call a customer from one outbound address share it.

Both are generous by default: they are meant to sit well above what a migration or a sync needs. They are deliberately not published as a number, because a number written into a client becomes a number we cannot move. Write your client to react to 429 and Retry-After, not to a figure.

A value that cannot be one of our access tokens is refused with invalid_token without being checked, but it still counts toward the per-address allowance. Send the token exactly as you received it, with nothing added around it.

Related guides

• Authentication
• Scopes
• Route reference
• Connected applications