Skip to content

Quickstart

From a new API key to your first response: sending the key, the /api/v1 endpoints and the error codes to handle.

1. Create a key

An organization admin creates keys in the dashboard under Developer. API access is included on Pro (Venue Pro for venues), and the plan is checked on every request, so a key stops working if the business moves down a plan.

The raw key is shown exactly once, when it is created, and cannot be recovered afterwards. Only a hash of it is stored.

sk_live_<key_id>_<secret>

To build against something that is not a real venue's book, choose Test when you create the key. A test key starts with sk_test_ and works only in your organization's API sandbox: a private venue with a few sample tables or one sample service, made the first time you create one. Bookings there never email or text anyone, and never appear among your real bookings.

2. Send it as a bearer token

Authorization: Bearer only. No query parameter, no custom header, no cookie fallback: a credential in a URL ends up in access logs, referrers and browser history.

curl https://gaplessly.com/api/v1/organization \  -H "Authorization: Bearer sk_live_..."

3. Call the endpoint for your engine

Every endpoint is under /api/v1/. Each :read scope has a list behind it, and the two booking engines also take writes.

EndpointScopeEngine
GET /api/v1/clientsclients:readEither
GET /api/v1/organizationorganization:readEither
GET /api/v1/availabilityavailability:readEither
GET /api/v1/servicesservices:readAppointments
GET /api/v1/providersproviders:readAppointments
GET /api/v1/appointmentsappointments:readAppointments
GET /api/v1/tablestables:readHospitality
GET /api/v1/service-periodsservice-periods:readHospitality
GET /api/v1/reservationsreservations:readHospitality
POST /api/v1/appointments, PATCH /api/v1/appointments/{id}, POST /api/v1/appointments/{id}/cancelappointments:writeAppointments
POST /api/v1/reservations, PATCH /api/v1/reservations/{id}, POST /api/v1/reservations/{id}/cancelreservations:writeHospitality

A create needs an Idempotency-Key header (a UUID per attempt, resent unchanged on a retry) so a retried request never books twice. A booking the business takes a deposit or a card for is never made unpaid: the create answers 402 payment_required with a bookingUrl for the guest to finish on the business's own booking page.

An engine-owned endpoint answers 403 wrong_vertical to a key from the other kind of organization, even when the key holds the scope: a scope says what a program may ask for, the engine says what the organization is.

4. Handle errors by code

Every failure is JSON with a human sentence and a stable code. Match on code, never on error.

{ "error": "human readable sentence", "code": "machine_readable_code" }
StatusCodeMeans
401missing_authorizationNo Authorization: Bearer header
401invalid_keyWrong format, unknown key or digest mismatch
401key_revoked / key_expiredRevoked in the dashboard, or past its expiry
403insufficient_scopeValid key, scope not held (required_scope says which)
403wrong_verticalThe route belongs to the other engine
403plan_requiredThe plan does not include API access
429rate_limitedOver the per-key limit for this window

A 401 means the credential is not usable, so retrying it will never succeed. A 403 means the credential is fine but may not do this.

On this page