API Surface & Support Policy

This page defines what marketplace vendors may call and the support policy
that governs how the API changes over time. Build to this surface and these
commitments so your integration keeps working as ROLLER evolves.

1. The API surface available to vendors

Marketplace vendors integrate with two API families, both authenticated with the
scoped OAuth2 key described in
Vendor App Auth & Credentials:

Every operation and its required scope is enumerated in the
Scoped Permissions catalog (81 grantable scopes) and
in the API Reference. A key holds either
REST API full access, Reporting API full access, or an explicit list of
granular scopes — see the auth guide for the model.

🚧

Restricted surface — Staff endpoints. All Staff endpoints

(/staff/*, scopes Staff_*) are restricted. They are never covered by
full access, must be explicitly granted on the key, and require the venue to
be enabled for the Staff Management API. Most marketplace apps neither need nor
should request them.

For the base URLs of each environment, see Environments and
Sandbox & Non-Prod Testing.

2. Versioning

📘

Current paths are unprefixed. Today the API is served without a version
prefix — the base URL is https://api.roller.app and endpoints are called

directly (e.g. GET /bookings/{uniqueId}), exactly as shown in the
API Reference. Do not add a /v1 prefix
to current endpoints. Always call the paths the API Reference shows.

The marketplace API contract commits to URL-path major versioning going
forward: when versioning is published, a major version will appear as a
path prefix (e.g. /v1), and the API Reference server URLs will be updated to
show it. Until the API Reference shows a version prefix, call endpoints
unprefixed. Within any major version:

• Additive, backward-compatible changes ship without a new version and without
  advance notice — new endpoints, new optional request fields, new response
  fields, and new enum values.
• Breaking changes are introduced under a new major version; the previous
  version continues to be served for the duration of its support window (below).

3. Your compatibility obligation

To stay compatible across additive changes, your integration must:

• Tolerate unknown fields in responses — ignore properties you do not
  recognise rather than failing to parse.
• Tolerate unknown enum values — treat an unrecognised enum as an
  "unknown/other" case, never as a hard error.
• Not depend on the ordering of fields or on undocumented behaviour.

Apps that follow these rules keep working across every additive update without
changes on your side.

4. Support window & breaking-change notice

During the notice period you should migrate to the new major version and verify
against a sandbox before the old version is retired.

5. Rate limits & availability

Rate limits apply per credential; exceeding them returns 429 (Too Many Requests). See Rate Limits and Errors for the
current limits, throttling behaviour, and retry guidance. Published quota and
availability targets (SLA) are provided separately as part of your vendor
agreement.

Next

• Sandbox & Non-Prod Testing — verify your integration
  against a non-prod tenant.
• Submission & Review — get your app approved
  and listed.