Lumbu API

v1
Lumbu Public API

Public REST API for Lumbu — a multi-tenant beauty-salon SaaS platform. Covers approved tenant-scoped bookings, services, products, checkout, staff portal, webhook subscriptions, and customer authentication. Lumbu owns staff/professionals, scheduling, tenant settings, analytics, and booking/lead data; only implemented operations appear here. Tenant API keys are limited to this `/api/v1` surface; platform administration and internal routes are intentionally excluded. CMS, media, and engagement remain tenant-specific. See docs/api-access-boundary.md.

Base URL: https://api.lumbu.pt

Authentication: pass your API key as Authorization: Bearer <key>

Tenant

GET
/api/v1/tenant

Get tenant metadata

Response

TenantMetadata

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/tenant" \
  -H "Authorization: Bearer {YOUR_API_KEY}"

Onboarding

GET
/api/v1/onboarding/check

Check tenant setup completeness

Returns a structured readiness check for the tenant's salon setup. Validates services, staff, hours, locations, payments, branding, locale, and notification templates.

Response

SetupCheckResult

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/onboarding/check" \
  -H "Authorization: Bearer {YOUR_API_KEY}"

Booking

GET
/api/v1/booking/packages

List active, currently bookable service packages

POST
/api/v1/booking/slots

Retrieve available booking slots

Request body

SlotsRequest

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/booking/slots" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/booking/book

Create a new booking

Request body

BookRequest

Response

BookResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/booking/book" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/booking/cancel

Cancel an existing booking

Request body

CancelRequest

Response

BookingCancellationResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/booking/cancel" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/booking/reschedule

Reschedule a booking to a new time

Request body

RescheduleRequest

Response

RescheduleResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/booking/reschedule" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

Services

GET
/api/v1/services

List services

Parameters

NameInTypeRequiredDescription
stringno
stringno
activequerystringnoFilter by active status[true, false]
booking_enabledquerystringnoFilter by booking-enabled flag[true, false]
updated_sincequerystring (date-time)noOnly return services updated on or after this timestamp

Response

PaginatedServiceList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/services" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/service-categories

List service categories with nested services

Checkout

POST
/api/v1/checkout

Create a Stripe checkout session

Request body

CheckoutRequest

Response

CheckoutResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/checkout" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

Customer

POST
/api/v1/customer/appointments

Get appointment detail and customer history

Request body

object

Response

CustomerAppointmentsResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/customer/appointments" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

Staff

GET
/api/v1/staff

List staff members

Parameters

NameInTypeRequiredDescription
stringno
stringno
activequerystringnoFilter by active status[true, false]
location_idquerystring (uuid)noFilter by location ID
updated_sincequerystring (date-time)noOnly return staff updated on or after this timestamp

Response

PaginatedStaffList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/team-members

List team member assignments

Parameters

NameInTypeRequiredDescription
stringno
stringno
location_idquerystring (uuid)noFilter by location ID
staff_idquerystring (uuid)noFilter by staff ID
joined_sincequerystring (date-time)noOnly return memberships created on or after this timestamp

Response

PaginatedTeamMemberList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/team-members" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-availability

Get computed staff availability

Parameters

NameInTypeRequiredDescription
fromquerystringyesStart date (YYYY-MM-DD)
staff_idquerystring (uuid)noFilter by staff ID
daysqueryintegernoNumber of days to look ahead

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-availability" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-hours

List staff recurring weekly hours

Parameters

NameInTypeRequiredDescription
stringno
stringno
staff_idquerystring (uuid)noFilter by staff ID
location_idquerystring (uuid)noFilter by location ID

Response

PaginatedStaffHoursList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-hours" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-time-off

List staff time-off periods

Parameters

NameInTypeRequiredDescription
stringno
stringno
staff_idquerystring (uuid)noFilter by staff ID
location_idquerystring (uuid)noFilter by location ID
start_at_gtequerystring (date-time)noFilter time-off starting on or after this timestamp
start_at_ltequerystring (date-time)noFilter time-off starting on or before this timestamp

Response

PaginatedStaffTimeOffList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-time-off" \
  -H "Authorization: Bearer {YOUR_API_KEY}"

Staff Portal

GET
/api/v1/staff-portal/url

Get the tenant's canonical staff portal URL

Resolves the canonical hosted staff URL from the tenant bound to the tenant API key. It does not accept tenant IDs, template keys, hosts, or return URLs from the caller. A verified staff_portal domain is preferred; a verified primary domain falls back to its /staff route.

Response

StaffPortalUrl

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/url" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/session

Get the authenticated staff portal session

Verifies the tenant API key and staff portal token, then returns the server-scoped tenant/staff identity, explicit permission flags, and the tenant staff time-management approval policy.

Parameters

NameInTypeRequiredDescription
stringno

Response

StaffPortalSession

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/session" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
POST
/api/v1/staff-portal/session/login

Login staff with email and password

Authenticates a staff member within the authenticated tenant and returns a Lumbu staff portal token plus staff session. Supabase user/session tokens and tenant/platform privileged operations are never returned.

Request body

StaffPortalLoginRequest

Response

StaffPortalSessionAuthResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/staff-portal/session/login" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/staff-portal/session/refresh

Refresh a staff portal session token

Parameters

NameInTypeRequiredDescription
stringno

Response

StaffPortalSessionAuthResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/staff-portal/session/refresh" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
POST
/api/v1/staff-portal/session/logout

Revoke a staff portal session token

Parameters

NameInTypeRequiredDescription
stringno

Response

OkResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/staff-portal/session/logout" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/dashboard

Get the staff portal dashboard aggregate

Parameters

NameInTypeRequiredDescription
stringno

Response

StaffPortalDashboard

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/dashboard" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/schedule

Get my or salon staff schedule

Returns appointments plus schedule context for the authenticated staff member (`scope=mine`) or salon (`scope=salon`). Tenant and staff identity are resolved server-side; salon appointment contact fields are redacted unless the staff member has appointment-management permission.

Parameters

NameInTypeRequiredDescription
stringno
scopequerystringno[mine, salon]
start_datequerystring (date)yesStart date (YYYY-MM-DD), maximum range 31 days
end_datequerystring (date)noEnd date (YYYY-MM-DD), defaults to start_date
target_staff_idquerystring (uuid)noOptional staff filter within the authenticated tenant

Response

StaffPortalSchedule

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/schedule" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/manager/salon-schedule

Get the manager salon schedule

Manager/admin-only salon schedule view with tenant-wide staff, appointments, client details, assigned staff, appointment state, and permissions-aware editing controls.

Parameters

NameInTypeRequiredDescription
stringno
start_datequerystring (date)yes
end_datequerystring (date)no
target_staff_idquerystring (uuid)no

Response

StaffPortalSchedule

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/manager/salon-schedule" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/appointments

List staff portal appointments

Parameters

NameInTypeRequiredDescription
stringno
windowquerystringno[upcoming, past]
statusquerystringno
staff_idquerystring (uuid)noManager-only staff filter; staff members may only request their own id.
limitqueryintegerno

Response

StaffPortalAppointmentListResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/appointments" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/appointments/upcoming

List upcoming staff portal appointments

Parameters

NameInTypeRequiredDescription
stringno
statusquerystringno
limitqueryintegerno

Response

StaffPortalAppointmentListResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/appointments/upcoming" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/appointments/past

List past staff portal appointments

Parameters

NameInTypeRequiredDescription
stringno
statusquerystringno
limitqueryintegerno

Response

StaffPortalAppointmentListResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/appointments/past" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
PATCH
/api/v1/staff-portal/appointments/{id}

Update a staff portal appointment status

Parameters

NameInTypeRequiredDescription
stringno
idpathstring (uuid)yes

Request body

StaffPortalAppointmentUpdateRequest

Response

StaffPortalAppointmentMutationResponse

Example

curl -X PATCH \
  "https://api.lumbu.pt/api/v1/staff-portal/appointments/{id}" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
GET
/api/v1/staff-portal/availability

Get my weekly staff availability

Parameters

NameInTypeRequiredDescription
stringno

Response

StaffPortalAvailabilityResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/availability" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
PUT
/api/v1/staff-portal/availability

Replace my weekly staff availability

Parameters

NameInTypeRequiredDescription
stringno

Request body

StaffPortalAvailabilityUpdateRequest

Response

StaffPortalAvailabilityUpdateResponse

Example

curl -X PUT \
  "https://api.lumbu.pt/api/v1/staff-portal/availability" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
GET
/api/v1/staff-portal/unavailability

List my one-off unavailability blocks

Parameters

NameInTypeRequiredDescription
stringno
start_at_gtequerystring (date-time)no
start_at_ltequerystring (date-time)no

Response

StaffPortalUnavailabilityListResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/unavailability" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
POST
/api/v1/staff-portal/unavailability

Create a one-off unavailability block

Parameters

NameInTypeRequiredDescription
stringno

Request body

StaffPortalUnavailabilityCreateRequest

Response

StaffPortalUnavailabilityBlock

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/staff-portal/unavailability" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
DELETE
/api/v1/staff-portal/unavailability/{id}

Delete my one-off unavailability block

Parameters

NameInTypeRequiredDescription
stringno
idpathstring (uuid)yes

Response

OkResponse

Example

curl -X DELETE \
  "https://api.lumbu.pt/api/v1/staff-portal/unavailability/{id}" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/time-off

List my time-off requests

Parameters

NameInTypeRequiredDescription
stringno
statusquerystringno[pending, approved, rejected, cancelled]
start_at_gtequerystring (date-time)no
start_at_ltequerystring (date-time)no

Response

StaffPortalTimeOffListResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/time-off" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
POST
/api/v1/staff-portal/time-off

Request time off

Creates a time-off request for the authenticated staff member. If the tenant approval policy is auto-approve, Lumbu also creates the matching staff_time_off availability block before returning the approved request.

Parameters

NameInTypeRequiredDescription
stringno

Request body

StaffPortalTimeOffCreateRequest

Response

StaffPortalTimeOffRequest

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/staff-portal/time-off" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
DELETE
/api/v1/staff-portal/time-off/{id}

Cancel my pending or approved time-off request

Parameters

NameInTypeRequiredDescription
stringno
idpathstring (uuid)yes

Response

OkResponse

Example

curl -X DELETE \
  "https://api.lumbu.pt/api/v1/staff-portal/time-off/{id}" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/shift-swaps

List my shift swap requests

Parameters

NameInTypeRequiredDescription
stringno
statusquerystringno

Response

StaffPortalShiftSwapListResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/shift-swaps" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
POST
/api/v1/staff-portal/shift-swaps

Request a shift swap

Parameters

NameInTypeRequiredDescription
stringno

Request body

StaffPortalShiftSwapCreateRequest

Response

StaffPortalShiftSwapMutationResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/staff-portal/shift-swaps" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
PATCH
/api/v1/staff-portal/shift-swaps/{id}

Accept or decline a received shift swap

Parameters

NameInTypeRequiredDescription
stringno
idpathstring (uuid)yes

Request body

StaffPortalShiftSwapRespondRequest

Response

StaffPortalShiftSwapMutationResponse

Example

curl -X PATCH \
  "https://api.lumbu.pt/api/v1/staff-portal/shift-swaps/{id}" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
DELETE
/api/v1/staff-portal/shift-swaps/{id}

Cancel a requested shift swap while it is pending

Parameters

NameInTypeRequiredDescription
stringno
idpathstring (uuid)yes

Response

OkResponse

Example

curl -X DELETE \
  "https://api.lumbu.pt/api/v1/staff-portal/shift-swaps/{id}" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/staff-portal/approval-policy

Get staff time-management approval policy

Parameters

NameInTypeRequiredDescription
stringno

Response

StaffPortalApprovalPolicy

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/staff-portal/approval-policy" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
PUT
/api/v1/staff-portal/approval-policy

Update staff time-management approval policy

Parameters

NameInTypeRequiredDescription
stringno

Request body

object

Response

StaffPortalApprovalPolicy

Example

curl -X PUT \
  "https://api.lumbu.pt/api/v1/staff-portal/approval-policy" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

Auth

POST
/api/v1/auth/signin

Sign in with email and password

Request body

SignInRequest

Response

SignInResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/auth/signin" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/auth/signup

Create a new customer account

Request body

SignUpRequest

Response

SignUpResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/auth/signup" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/auth/magic-link

Send a passwordless magic link email

Request body

MagicLinkRequest

Response

OkResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/auth/magic-link" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/auth/refresh

Refresh an authentication token

Request body

RefreshRequest

Response

RefreshResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/auth/refresh" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

Products

plugin
GET
/api/v1/products

List products

Parameters

NameInTypeRequiredDescription
stringno
stringno
activequerystringnoFilter by active_for_sale status (defaults to true)[true, false]
category_idquerystring (uuid)noFilter by product category
updated_sincequerystring (date-time)noOnly return products updated on or after this timestamp

Response

PaginatedProductList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/products" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/products/{id}

Get product detail by ID or slug

Parameters

NameInTypeRequiredDescription
idpathstringyesProduct UUID or slug

Response

ProductDetail

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/products/{id}" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/product-categories

List product categories with product counts

Other

plugin
GET
/api/v1/appointments

List appointments

Parameters

NameInTypeRequiredDescription
stringno
stringno
start_at_gtequerystring (date-time)noFilter appointments starting on or after this timestamp
start_at_ltequerystring (date-time)noFilter appointments starting on or before this timestamp
statusquerystringnoFilter by appointment status[requested, confirmed, cancelled, completed, no_show]
location_idquerystring (uuid)noFilter by location ID
staff_idquerystring (uuid)noFilter by staff ID
service_idquerystring (uuid)noFilter by service ID
updated_sincequerystring (date-time)noOnly return appointments updated on or after this timestamp

Response

PaginatedAppointmentList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/appointments" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/appointment-feedback

List appointment feedback entries

Parameters

NameInTypeRequiredDescription
stringno
stringno
appointment_idquerystring (uuid)noFilter by appointment ID
updated_sincequerystring (date-time)noOnly return feedback updated on or after this timestamp

Response

PaginatedFeedbackList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/appointment-feedback" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/locations

List locations

Parameters

NameInTypeRequiredDescription
stringno
stringno
is_activequerystringnoFilter by active status[true, false]
updated_sincequerystring (date-time)noOnly return locations updated on or after this timestamp

Response

PaginatedLocationList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/locations" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
GET
/api/v1/waitlist

List waitlist entries

Parameters

NameInTypeRequiredDescription
stringno
stringno
location_idquerystring (uuid)noFilter by location ID
service_idquerystring (uuid)noFilter by service ID
staff_idquerystring (uuid)noFilter by staff ID
created_at_gtequerystring (date-time)noFilter entries created on or after this timestamp
created_at_ltequerystring (date-time)noFilter entries created on or before this timestamp

Response

PaginatedWaitlistList

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/waitlist" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
POST
/api/v1/gift-cards/validate

Validate a gift card code

Request body

object

Response

GiftCardValidationResponse

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/gift-cards/validate" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
GET
/api/v1/referral/validate

Validate a referral code format

Parameters

NameInTypeRequiredDescription
codequerystringyesReferral code to validate (alphanumeric, 3-50 chars, hyphens/underscores allowed)

Response

ReferralValidationResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v1/referral/validate" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
POST
/api/v1/orders/lookup

Look up an order by session ID or access token

Request body

OrderLookupRequest

Response

Order

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/orders/lookup" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

Webhooks

plugin
GET
/api/v1/webhooks

List webhook subscriptions

POST
/api/v1/webhooks

Register a new webhook subscription

Request body

CreateWebhookRequest

Response

WebhookSubscriptionCreated

Example

curl -X POST \
  "https://api.lumbu.pt/api/v1/webhooks" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
DELETE
/api/v1/webhooks/{id}

Delete a webhook subscription

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesWebhook subscription ID

Response

OkResponse

Example

curl -X DELETE \
  "https://api.lumbu.pt/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer {YOUR_API_KEY}"