v1

Making requests

Base URL, authentication header, pagination and error handling.

The Verbleif API is an API Platform JSON-LD API. Every request is authenticated with the bearer token you obtained during Authentication.

Base URL and headers

Send the access token in the Authorization header. Ask for JSON-LD with Accept, and send JSON-LD bodies with Content-Type when you write data:

curl https://api.verbleif.com/api/reservations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/ld+json"
Header When Value
Authorization Every request Bearer YOUR_ACCESS_TOKEN
Accept Every request application/ld+json
Content-Type Request bodies (POST, PUT, …) application/ld+json
Content-Type Partial updates (PATCH) application/merge-patch+json

The API only negotiates JSON-LD (application/ld+json) for resource responses and errors. Plain application/json is not a supported response format. OpenAPI / HTML docs use separate media types (application/vnd.openapi+json, text/html) and are not used for normal API calls.

Pagination

Collection endpoints are paginated with API Platform Hydra / JSON-LD collections.

Query parameter Default Notes
page 1 Page number
perPage 100 Page size; clients may raise this up to 250
partial unset (false) When true, the API skips computing the total count

A typical first page looks like:

{
  "member": [ /* …resources… */ ],
  "totalItems": 160,
  "view": {
    "@type": "PartialCollectionView",
    "first": "/api/clients?page=1",
    "last": "/api/clients?page=2",
    "next": "/api/clients?page=2"
  }
}

Total count (totalItems)

totalItems is returned only on the first page (page=1, or omitted). Later pages omit it so the API can avoid a full count query. The same applies when you pass partial=true: even page 1 has no totalItems.

If you need the total, read it from the first response and keep paging with the links in view.

Follow the next link in view until it is absent. Do not hard-code page numbers or assume a fixed page size beyond the defaults above.

Rate limits

Authenticated App Store / API Platform calls to normal resource endpoints (/api/… with a bearer token) do not currently apply a global per-app or per-token request quota in the API.

Abuse-sensitive endpoints use Symfony’s token bucket rate limiter (token_bucket): a burst capacity that refills at a fixed rate. When a bucket is empty the API responds with 429 Too Many Requests and a Retry-After header (seconds until you may retry). Always handle 429 and honour Retry-After.

Examples of endpoint-specific buckets (not a general API quota):

Area Bucket Burst (limit) Refill
Public guest reports (write / settings / discovery) per client IP and per location hash 50 10 tokens / minute
Public guest report reads per client IP and per location hash 30 6 tokens / minute
Password recovery (by IP) per IP 100 20 tokens / minute
Password recovery (by username) per username 5 1 token / minute

Login discovery on the auth service uses the same token-bucket algorithm (separate buckets per IP and per username). Those limits apply to discovery, not to ordinary App Store API traffic.

There is no published global “requests per minute per app” figure for authenticated collection and item endpoints. If you receive 429 on those paths, treat it as an exceptional throttle (edge or endpoint-specific) and back off using Retry-After.

Errors

The API uses standard HTTP status codes. Error responses are also returned as JSON-LD (same Accept) and include machine-readable fields such as status and detail:

{
  "status": 403,
  "detail": "This app is not authorized for the requested scope."
}
  • 401 - the access token is missing or expired. Refresh it and retry.
  • 403 - the token is valid but the app lacks the required scope.
  • 404 - the resource does not exist or is outside the granted locations.
  • 429 - you are being rate limited; honour Retry-After.
  • 406 - the Accept header does not match a supported format (use application/ld+json).

For App Store integrations that push changes into Verbleif from an external system, see Webhooks.