Bookings

Requires an API key — see Authentication & Scopes.

GET /bookings

List bookings for your space. Cursor-paginated — see Pagination. Scope: bookings:read.

curl https://api.tatiya.space/v1/bookings \
  -H "Authorization: Bearer $TATIYA_API_KEY"

POST /bookings

Create a booking on the host's behalf. Scope: bookings:write.

curl -X POST https://api.tatiya.space/v1/bookings \
  -H "Authorization: Bearer $TATIYA_API_KEY" \
  -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]" }
  }'

Two request fields need bookings:override in addition to bookings:write, and are checked before the booking runs — a key without the override scope gets a clean insufficient_scope rather than the override silently failing to apply:

• allow_over_capacity — book past the session's stated capacity
• allow_policy_bypass — book outside the space's usual booking window

Both are decisions a host makes about their own space. Only offer them where a human at the host end has actually chosen to override something, and only after telling them what they're overriding.

GET /bookings/{id}

Read one booking, including membership coverage if it was covered by one. Scope: bookings:read.

curl https://api.tatiya.space/v1/bookings/$BOOKING_ID \
  -H "Authorization: Bearer $TATIYA_API_KEY"

PATCH /bookings/{id}

Update a booking's notes or its source. Scope: bookings:write. Send only the fields you want to change — notes and source are updated independently.

curl -X PATCH https://api.tatiya.space/v1/bookings/$BOOKING_ID \
  -H "Authorization: Bearer $TATIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Called ahead about a knee injury" }'

notes is the host's own operational note, editable after the fact — not the note the customer submitted when they booked, which is a separate, unrelated field.

POST /bookings/{id}/cancel

Scope: bookings:write.

curl -X POST https://api.tatiya.space/v1/bookings/$BOOKING_ID/cancel \
  -H "Authorization: Bearer $TATIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer requested" }'

POST /bookings/{id}/check-in

Mark a customer as having arrived. Scope: bookings:write.

curl -X POST https://api.tatiya.space/v1/bookings/$BOOKING_ID/check-in \
  -H "Authorization: Bearer $TATIYA_API_KEY"

POST /bookings/{id}/payment

Record a payment against a booking. Scope: bookings:write. Omit amount_minor to record the booking's own priced amount rather than guessing a number yourself.

curl -X POST https://api.tatiya.space/v1/bookings/$BOOKING_ID/payment \
  -H "Authorization: Bearer $TATIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "method": "promptpay" }'

When a booking is refused

A 409 on booking creation carries a booking_failure — see Errors for the outer shape:

{
  "error": {
    "type": "conflict",
    "message": "This session is full",
    "booking_failure": {
      "reason": "capacity_full",
      "override": "allow_over_capacity"
    }
  }
}

reason says what stopped it. override names the flag that would let it through, or is null when nothing would.

reason	What to do
capacity_full	Offer another slot, or the override to a host
policy_window	Too far ahead or too close to the session — show the space's window
duplicate_booking	They already hold this one — link to it instead
bookings_disabled	The space has bookings switched off entirely
booking_type_not_found	Refresh your cached offering — it may have changed
space_unavailable	The space is unpublished or suspended
tier_blocked	The space is over its plan's limit — not the customer's problem, don't say so

Show the customer the reason. Only offer the override to a host, and only after they know what they're overriding.