Versioning

The API uses a stable /v1 path together with date-based versioning carried in a request header. This lets us evolve response shapes over time without breaking existing integrations.

The Service-Version header

Versions are date strings, for example 2026-06-27. Send one with any request:

curl https://api.useservice.app/v1/reservations \
  -H "Authorization: Bearer $SERVICE_API_KEY" \
  -H "Service-Version: 2026-06-27"

How the version is resolved

1. Pinned per key. Each API key is pinned to a version when it is created. If you send no Service-Version header, that pinned version is used. This means your integration keeps working unchanged even as new versions ship.
2. Per-request override. If you send a Service-Version header, it overrides the key’s pinned version for that single request — useful for testing a newer version before adopting it.

Echoed in responses

Every response echoes the version that served it, so you can confirm exactly which behaviour you got:

HTTP/1.1 200 OK
Service-Version: 2026-06-27
Content-Type: application/json

Current version

There is currently a single version: 2026-06-27. When new versions are introduced, this page will list them along with the changes each one makes. Webhook endpoints are likewise pinned to a version at creation, so the payloads you receive stay consistent. See Webhooks.