API v1

The Partner API is versioned by URL prefix:

https://stage.cbms.venuesetu.com/api/v1
https://cbms.venuesetu.com/api/v1

There is no v2 today.

Policy

• Additive changes stay in v1 — new optional fields, new endpoints, new webhook event types. Ignore properties you do not recognize.
• Breaking changes require a new prefix. We will not silently rename or remove v1 fields.
• Deprecations are announced in the changelog with a transition period.

GET /api/v1/openapi.json (no auth) is the field-level contract. This site also ships a copy at openapi.json and a browsable reference.

Task map

You need to…	Start here
Know which venues you can book	Venues
Know court/field ids	Resources
Show a day’s grid	Availability
Reserve while the customer pays	Holds
Commit after payment	Bookings
Undo a booking	Cancellations
Sell a credit pack	Packages
Queue a customer on a full slot	Waitlist
Hear about other channels’ bookings	Webhooks

All of the above require x-api-key except the OpenAPI document itself.

Errors

Bodies look like:

{
  "error": "SLOT_NOT_AVAILABLE",
  "message": "Slot is currently HELD",
  "request_id": "…"
}

request_id matches the X-Request-Id response header. Quote it if you contact support. Every response carries X-Request-Id, but a few validation errors (for example a missing required query parameter on waitlist or active-package reads) return only { "error": "<sentence>" } without a code or request_id in the body — read the header in that case, and treat any 400 as a request to fix.

Treat 5xx as transient: retry with the same idempotency_key. Treat 4xx as terminal except 409 (inspect error) and 429 (honour Retry-After).