Versioning

The version lives in the URL. /v1 is the only version, every route sits under it, and it is the only thing you pin.

https://{your-base-url}/v1

There is no version header, no dated-version scheme, and nothing to configure beyond the base URL. The OpenAPI document reports info.version (1.0.0 today), which moves as the surface grows — but the /v1 in your base URL is the contract.

What will not change under you

While /v1 exists:

• An endpoint will not be removed, and its path will not change.
• A field will not be removed from a response, and its type will not change.
• A field will not become required on a request that did not require it.
• A response field’s meaning will not change. net_payable will not quietly start including commission.

A change that breaks any of those is a /v2, announced ahead of time, with /v1 running alongside it while you migrate.

What may change without notice

These are all additive, and a client that is not built to tolerate them will break on a change we consider routine.

New fields may appear in any response. Ignore what you do not recognise. If your deserializer rejects unknown fields — some strict JSON libraries do by default — turn that off for our responses, or you will break on a release that broke nobody else.

New values may appear in any enum. This is the one that catches people, and status is where it catches them.

More than one not-yet-confirmed booking status exists, new ones may be added, and they carry no obligation you need to treat differently. So write:

if (booking.status === 'confirmed') { /* it is on */ }
else                                { /* it is not on yet */ }

and not a switch that enumerates every status you have seen so far. The same applies to trip_state, to error codes, and to any other closed-looking set. An exhaustive match over values we may extend is a bug with a delay on it.

New optional query parameters and new optional body fields may appear. Ignore them until you need them.

New endpoints may appear. New scopes may appear alongside them — your existing credentials keep working, they simply will not hold the new scope until you mint one that does.

Error messages may be reworded. error.code is the stable half; parse that and never error.message. See Errors.

Nothing in /v1 is deprecated today.

Sandbox and production

The same /v1, on two hosts, with separate credentials.

Your sandbox base URL is what this site and the published OpenAPI document describe — every example writes it as https://{your-base-url}. You receive the production base URL at go-live along with your production credentials, and it is the one value you change.

Changes reach sandbox first. Integrate there, and keep a sandbox credential alive after go-live — it is where you will verify the next change you make.

Getting the spec

The checked-in document behind the API Reference is served from this site, so it renders even when the API is down — which is exactly when a partner debugging an outage needs to read it.

A running server also serves its own, unauthenticated, at:

GET https://{your-base-url}/v1/openapi.json

That one derives its servers entry from the host you asked, so a client generated from it calls the environment you fetched it from. Regenerate your client from it after any change you care about, and treat a diff in the generated types as the changelog.