Skip to content

Conventions

What is true of every endpoint: errors, paging, times, rate limits and versioning.

The organization comes from the credential

No endpoint takes an organization id. A key belongs to one organization, and every /api/v1 response is that organization's data and nothing else. The public endpoints name the business by the slug in their path, the same one its booking page lives at.

Errors are one shape

Every non-2xx body is JSON with a human sentence in error. /api/v1 adds a machine-readable code beside it: match on the code, never on the sentence. On the public endpoints the HTTP status is the code.

Lists page with a cursor

Every /api/v1 list answers { data: [...], nextCursor }. Pass nextCursor back as cursor for the next page; it is null exactly when there are no more rows. Treat it as an opaque token and never build one yourself. limit defaults to 50 and is clamped to 200.

Booking times are the venue's wall clock

A booking's startsAt and endsAt are the venue's local time wearing a +00 suffix, not UTC instants: a 19:00 booking in Sydney comes back as 19:00:00+00. createdAt and holdExpiresAt are true UTC instants. Read the venue's zone from timezone on GET /api/v1/organization before converting anything, or every booking shifts by the venue's whole offset.

Fields are camelCase, with marked exceptions

Request bodies and every /api/v1 response are camelCase. A few public booking confirmations return a booking exactly as stored, in snake_case, and each of those says so at the operation.

Double-booking is a database guarantee

Overlap is prevented by the database itself, not by an application check, so two guests can never hold the same slot. Whoever loses the race gets a 409. The public flows check the requested time again server-side rather than trusting a posted one, so an availability read is a guide, not a promise.

Rate limits

API keys get a per-key fixed 60-second window, 120 requests a minute by default. Every /api/v1 response states the policy in RateLimit-Policy (IETF httpapi draft), and every response to a known key adds RateLimit with what is left, plus the older X-RateLimit-* trio. A 429 also carries Retry-After. The public endpoints that write are limited per visitor.

Versioning is explicit, and deprecation has a floor

/api/v1/ is a real version segment, not decoration. Adding a field, an endpoint or a scope is never a breaking change; one is reserved for an actual break to a published shape. When a v2 ships, v1 keeps answering unchanged for a notice window of at least 6 months, and every v1 response carries Deprecation and Sunset headers (RFC 9745, RFC 8594) for that whole window, not only a changelog entry. The one exception is a security fix: if keeping v1 running would expose data, the window can be shorter, and the notice says why. There is no v2 yet, so neither header is on the wire today.

A malformed id is a 404

A path id that is not a valid uuid, or that belongs to another business, is a 404, never a 500. An id in the body that does not resolve is usually a 400 instead: a validation failure, not a missing resource.

No CORS, on purpose

No endpoint sends CORS headers. An API key is a secret, so /api/v1 belongs on a server: a browser calling it directly would be publishing the key to every visitor.

On this page