Skip to main content

Public Surface

No API key needed. These routes serve exactly what a visitor can already see on a space's own website — its profile, its booking types, real availability, and its published posts — plus one write: booking as a guest. They're cacheable, CORS-open, and the only part of the API that's safe to call from a browser.

Every example below uses sunrise — our demo space, always available to try against.

Routes are keyed by handle, not by id​

{handle} is the space's subdomain — the thing a third party actually knows, not an internal identifier. sunrise.tatiya.space → handle sunrise.

GET /public/{handle}​

The space's public profile.

curl https://api.tatiya.space/v1/public/sunrise

GET /public/{handle}/booking-types​

What the space offers, cursor-paginated (see Pagination).

curl https://api.tatiya.space/v1/public/sunrise/booking-types

GET /public/{handle}/booking-types/{id}/availability​

Real, current availability for one booking type over a date range. Times come back wall-clock, with the space's timezone alongside — see Money, dates and times.

curl "https://api.tatiya.space/v1/public/sunrise/booking-types/$TYPE_ID/availability?from=2026-09-01&to=2026-09-07"

A slot here is not a hold — capacity is settled inside the booking transaction itself, so expect 409 capacity_full on a popular slot and handle it (offering the next slot is a better experience than surfacing an error).

GET /public/{handle}/posts​

The space's published blog posts, if it has any.

curl https://api.tatiya.space/v1/public/sunrise/posts

POST /public/{handle}/bookings​

Book a session as a guest. No key required.

curl -X POST https://api.tatiya.space/v1/public/sunrise/bookings \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "booking_type_id": "'"$TYPE_ID"'",
    "scheduled_date": "2026-09-01",
    "scheduled_start_time": "07:00",
    "customer": { "name": "Ari", "email": "[email protected]" },
    "source": "external_partner",
    "marketing_consent": false
  }'

A few things worth getting right:

  • Always send an Idempotency-Key. See Idempotency — this is the route where skipping it costs the most: a retried timeout without one books the same person twice.
  • Send source: external_partner. It's a real value in the platform's own enum, and it's what lets a host's own reporting show where a booking came from. Sending nothing attributes your bookings to the space's own website.
  • marketing_consent defaults to false, and should stay that way unless the customer actually agreed, in words they saw. The platform records the consent text and the timestamp — a true you didn't earn is a compliance problem for the host, not for you.
  • Store the returned booking id. It's the handle you'll need for cancel, check-in and payment once you have an authenticated key — see Bookings.