Developers · Start here
Errors, dates, languages and limits
How the API answers, the formats it uses, and the limits it applies.
Answers
Success: { "data": ... } with 200 (or 201 when something was created).
Error:
{ "error": { "code": "unprocessable", "message": "phone: not a valid number.", "field": "phone" } }
message is readable and safe to show to the user, in the request’s language. field names the field at fault; reason gives
a machine-readable detail where useful (signup_required, gone, limit, full, capacity, minNights).
| HTTP | code |
When |
|---|---|---|
| 400 | bad_request |
Unknown or missing field, bad JSON, bad date or range |
| 401 | unauthorized |
Missing or invalid key or token; wrong sign-in code |
| 403 | forbidden |
Read-only key on a change; account waiting for approval; team account at customer sign-in |
| 404 | not_found |
No such endpoint or thing, or not available for this kind of venue |
| 405 | method_not_allowed |
Wrong method (see the Allow header) |
| 409 | conflict |
Full, taken, already booked, an unpaid pack already open |
| 422 | unprocessable |
A value is not acceptable |
| 429 | rate_limited |
Too many requests (see Retry-After) |
| 500 | server_error |
Our side; check the current state before retrying a change |
Unknown fields are refused with 400, in the query string and in the body. A typo never passes silently.
Dates, times, money
- Dates are
YYYY-MM-DD, timesHH:MM, both in the venue’s time zone:Europe/Athens. - Timestamps (
starts_at,expires,joined) are ISO 8601 in UTC. - Money is euro, as a number:
"price_eur": 59.9. Prices are as the venue set them. - Ids are opaque strings; do not parse them (class ids happen to contain a date, but treat them as opaque).
Languages
Send ?lang=el (or en, or any language the venue offers), or an Accept-Language header. Error messages and names the venue
translated (classes, packs, services, units) come back in that language. Otherwise the venue’s default language is used.
Requests
GETandDELETEtake their fields in the query string; lists are comma-separated (?member_ids=a,b).POST,PUTandPATCHtake a JSON object body (Content-Type: application/json).- Path parameters are ids:
/admin/members/{member_id}. PATCHchanges only the fields you send.
Limits
| Who | Limit |
|---|---|
| API key | 120 requests a minute per key |
| Public and customer reads | 240 a minute per IP |
| Public and customer writes | 30 a minute per IP |
| Guest bookings | 10 an hour per IP and 5 an hour per email, per venue |
| Sign-in codes | a few per email and per IP every 15 minutes |
| Imports | 100 rows per call |
On 429, wait for Retry-After seconds.
Retries
GET is always safe to retry. A change that timed out may have happened: check before repeating (for example
GET /me/bookings before booking again). Imports are safe to repeat: rows carry your own external_id.
CORS
Open to all origins, so browser apps can call the public and customer endpoints directly. The admin API works from browsers too, technically, but an API key must never be in a browser.
Versions
This is v1. New fields and endpoints are added without a new version; existing fields keep their meaning. See the
changelog.