Lumbu API

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. The ready result is authoritative when services, staff, staff hours, staff-service links, locations, and business hours all pass. Payment, branding, locale, and notification checks are informational only.

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

Parameters

Name	In	Type	Required	Description
commercial_offer_key	query	string	no	Selects the typed Ukembu hair-therapy offer representation for its configured package. Omit this parameter to preserve the generic package response.

Example

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

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

Parameters

Name	In	Type	Required	Description
		string	no	—

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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
active	query	string	no	Filter by active status[true, false]
booking_enabled	query	string	no	Filter by booking-enabled flag[true, false]
classification	query	string	no	Filter by canonical structured service classification[hair_evaluation, hair_therapy_session, hair_therapy_programme, head_spa, braids, other_hair_service, other]
updated_since	query	string (date-time)	no	Only 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

GET

/api/v1/customer/appointments

List appointments for the signed-in customer

Uses the tenant-scoped customer session cookie. The browser can load this list independently after the profile shell renders.

Response

CustomerAppointmentListResponse

Example

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

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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
active	query	string	no	Filter by active status[true, false]
location_id	query	string (uuid)	no	Filter by location ID
updated_since	query	string (date-time)	no	Only 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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
location_id	query	string (uuid)	no	Filter by location ID
staff_id	query	string (uuid)	no	Filter by staff ID
joined_since	query	string (date-time)	no	Only 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

Name	In	Type	Required	Description
from	query	string	yes	Start date (YYYY-MM-DD)
staff_id	query	string (uuid)	no	Filter by staff ID
days	query	integer	no	Number 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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
staff_id	query	string (uuid)	no	Filter by staff ID
location_id	query	string (uuid)	no	Filter 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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
staff_id	query	string (uuid)	no	Filter by staff ID
location_id	query	string (uuid)	no	Filter by location ID
start_at_gte	query	string (date-time)	no	Filter time-off starting on or after this timestamp
start_at_lte	query	string (date-time)	no	Filter 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/v2/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/v2/staff-portal/url" \
  -H "Authorization: Bearer {YOUR_API_KEY}"

GET

/api/v2/staff-portal/session

Get the authenticated staff portal session

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

Parameters

Name	In	Type	Required	Description
		string	no	—

Response

StaffPortalSession

Example

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

POST

/api/v2/staff-portal/session/logout

Revoke an opaque staff adapter session

Parameters

Name	In	Type	Required	Description
		string	no	—

Response

OkResponse

Example

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

GET

/api/v2/staff-portal/dashboard

Get the staff portal dashboard aggregate

Returns today and next appointments, alerts, and the approval policy. It does not include earnings, commissions, sales, or targets.

Parameters

Name	In	Type	Required	Description
		string	no	—

Response

StaffPortalDashboard

Example

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

GET

/api/v2/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

Name	In	Type	Required	Description
		string	no	—
scope	query	string	no	—[mine, salon]
start_date	query	string (date)	yes	Start date (YYYY-MM-DD), maximum range 31 days
end_date	query	string (date)	no	End date (YYYY-MM-DD), defaults to start_date
target_staff_id	query	string (uuid)	no	Optional staff filter within the authenticated tenant

Response

StaffPortalSchedule

Example

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

GET

/api/v2/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

Name	In	Type	Required	Description
		string	no	—
start_date	query	string (date)	yes	—
end_date	query	string (date)	no	—
target_staff_id	query	string (uuid)	no	—

Response

StaffPortalSchedule

Example

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

GET

/api/v2/staff-portal/appointments

List staff portal appointments

Parameters

Name	In	Type	Required	Description
		string	no	—
window	query	string	no	—[upcoming, past]
status	query	string	no	—
staff_id	query	string (uuid)	no	Manager-only staff filter; staff members may only request their own id.
limit	query	integer	no	—

Response

StaffPortalAppointmentListResponse

Example

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

POST

/api/v2/staff-portal/appointments

Create a staff portal appointment

Parameters

Name	In	Type	Required	Description
		string	no	—

Request body

StaffPortalAppointmentCreateRequest

Response

StaffPortalAppointmentCreateResponse

Example

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

GET

/api/v2/staff-portal/booking-options

List bookable services for a staff member

Parameters

Name	In	Type	Required	Description
		string	no	—
staff_id	query	string (uuid)	no	Manager-only target staff member. Defaults to the authenticated staff member.

Response

StaffPortalBookingOptionsResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v2/staff-portal/booking-options" \
  -H "Authorization: Bearer {YOUR_API_KEY}"

GET

/api/v2/staff-portal/active-services

List active bookable services for the salon team

Lists active bookable services assigned to at least one active team member. Requires team appointment management permission.

Parameters

Name	In	Type	Required	Description
		string	no	—

Response

StaffPortalActiveServicesResponse

Example

curl -X GET \
  "https://api.lumbu.pt/api/v2/staff-portal/active-services" \
  -H "Authorization: Bearer {YOUR_API_KEY}"

GET

/api/v2/staff-portal/customers

Search or inspect Customer 360 records

Searches customers within the authenticated staff member's permitted team scope. Pass customer_key to load one profile. Generic results exclude Care Vault and other protected health or sensitive history.

Parameters

Name	In	Type	Required	Description
		string	no	—
q	query	string	no	Search by customer name, phone, or email
customer_key	query	string	no	Exact customer email or opaque anonymous customer key
limit	query	integer	no	—

Example

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

POST

/api/v2/staff-portal/customers/notes

Add an internal customer note

Parameters

Name	In	Type	Required	Description
		string	no	—
		string	no	—

Request body

object

Example

curl -X POST \
  "https://api.lumbu.pt/api/v2/staff-portal/customers/notes" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH

/api/v2/staff-portal/customers/notes/{id}

Update an internal customer note

Parameters

Name	In	Type	Required	Description
		string	no	—
id	path	string (uuid)	yes	—
		string	no	—

Request body

object

Example

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

DELETE

/api/v2/staff-portal/customers/notes/{id}

Delete an internal customer note

Parameters

Name	In	Type	Required	Description
		string	no	—
id	path	string (uuid)	yes	—
		string	no	—

Example

curl -X DELETE \
  "https://api.lumbu.pt/api/v2/staff-portal/customers/notes/{id}" \
  -H "Authorization: Bearer {YOUR_API_KEY}"

GET

/api/v2/staff-portal/catalog/services

List canonical services, prices, variants, and booking compatibility

Scope defaults to the authenticated professional. Team scope requires team appointment permission.

Parameters

Name	In	Type	Required	Description
		string	no	—
scope	query	string	no	—[mine, team]
service_id	query	string (uuid)	no	—

Example

curl -X GET \
  "https://api.lumbu.pt/api/v2/staff-portal/catalog/services" \
  -H "Authorization: Bearer {YOUR_API_KEY}"

POST

/api/v2/staff-portal/catalog/availability

Calculate real available slots for a service

Read-only availability calculation using canonical shifts, breaks, time off, appointments, buffers, variants, and tenant rules.

Parameters

Name	In	Type	Required	Description
		string	no	—

Request body

object

Example

curl -X POST \
  "https://api.lumbu.pt/api/v2/staff-portal/catalog/availability" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

GET

/api/v2/staff-portal/inventory

List read-only staff inventory visibility

Returns product, brand, category, SKU, location placeholder, quantity, and low-stock state. Cost and wholesale data are never returned.

Parameters

Name	In	Type	Required	Description
		string	no	—
q	query	string	no	—
limit	query	integer	no	—

Example

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

GET

/api/v2/staff-portal/performance

Get personal operational performance metrics

Returns only the authenticated staff member's metrics. Revenue, earnings, commission, tips, and team-wide data are excluded.

Parameters

Name	In	Type	Required	Description
		string	no	—
start	query	string (date)	no	—
end	query	string (date)	no	—

Example

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

GET

/api/v2/staff-portal/appointments/upcoming

List upcoming staff portal appointments

Parameters

Name	In	Type	Required	Description
		string	no	—
status	query	string	no	—
limit	query	integer	no	—

Response

StaffPortalAppointmentListResponse

Example

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

GET

/api/v2/staff-portal/appointments/past

List past staff portal appointments

Parameters

Name	In	Type	Required	Description
		string	no	—
status	query	string	no	—
limit	query	integer	no	—

Response

StaffPortalAppointmentListResponse

Example

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

GET

/api/v2/staff-portal/follow-ups

List my pending client follow-ups

Parameters

Name	In	Type	Required	Description
		string	no	—

Example

curl -X GET \
  "https://api.lumbu.pt/api/v2/staff-portal/follow-ups" \
  -H "Authorization: Bearer {YOUR_API_KEY}"

POST

/api/v2/staff-portal/follow-ups

Create an idempotent client follow-up

Parameters

Name	In	Type	Required	Description
		string	no	—
		string	no	—

Request body

object

Example

curl -X POST \
  "https://api.lumbu.pt/api/v2/staff-portal/follow-ups" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH

/api/v2/staff-portal/follow-ups/{id}

Complete, reopen, or update a client follow-up

Parameters

Name	In	Type	Required	Description
		string	no	—
id	path	string (uuid)	yes	—
		string	no	—

Request body

object

Example

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

PATCH

/api/v2/staff-portal/follow-ups/programmes/{id}

Complete or dismiss a programme follow-up action

Manager-scoped transition for conversion, next-session, retention, and overdue programme actions.

Parameters

Name	In	Type	Required	Description
		string	no	—
id	path	string (uuid)	yes	—
		string	no	—

Request body

object

Example

curl -X PATCH \
  "https://api.lumbu.pt/api/v2/staff-portal/follow-ups/programmes/{id}" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH

/api/v2/staff-portal/appointments/{id}

Update a staff portal appointment status or duration

Parameters

Name	In	Type	Required	Description
		string	no	—
id	path	string (uuid)	yes	—

Request body

StaffPortalAppointmentUpdateRequest

Response

StaffPortalAppointmentMutationResponse

Example

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

GET

/api/v2/staff-portal/availability

Get my weekly staff availability

Parameters

Name	In	Type	Required	Description
		string	no	—

Response

StaffPortalAvailabilityResponse

Example

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

PUT

/api/v2/staff-portal/availability

Replace my weekly staff availability

Parameters

Name	In	Type	Required	Description
		string	no	—

Request body

StaffPortalAvailabilityUpdateRequest

Response

StaffPortalAvailabilityUpdateResponse

Example

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

GET

/api/v2/staff-portal/unavailability

List my one-off unavailability blocks

Parameters

Name	In	Type	Required	Description
		string	no	—
start_at_gte	query	string (date-time)	no	—
start_at_lte	query	string (date-time)	no	—

Response

StaffPortalUnavailabilityListResponse

Example

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

POST

/api/v2/staff-portal/unavailability

Create a one-off unavailability block

Parameters

Name	In	Type	Required	Description
		string	no	—

Request body

StaffPortalUnavailabilityCreateRequest

Response

StaffPortalUnavailabilityBlock

Example

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

DELETE

/api/v2/staff-portal/unavailability/{id}

Delete my one-off unavailability block

Parameters

Name	In	Type	Required	Description
		string	no	—
id	path	string (uuid)	yes	—

Response

OkResponse

Example

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

GET

/api/v2/staff-portal/time-off

List my time-off requests

Parameters

Name	In	Type	Required	Description
		string	no	—
status	query	string	no	—[pending, approved, rejected, cancelled]
start_at_gte	query	string (date-time)	no	—
start_at_lte	query	string (date-time)	no	—

Response

StaffPortalTimeOffListResponse

Example

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

POST

/api/v2/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

Name	In	Type	Required	Description
		string	no	—

Request body

StaffPortalTimeOffCreateRequest

Response

StaffPortalTimeOffRequest

Example

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

DELETE

/api/v2/staff-portal/time-off/{id}

Cancel my pending or approved time-off request

Parameters

Name	In	Type	Required	Description
		string	no	—
id	path	string (uuid)	yes	—

Response

OkResponse

Example

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

GET

/api/v2/staff-portal/shift-swaps

List my shift swap requests

Parameters

Name	In	Type	Required	Description
		string	no	—
status	query	string	no	—

Response

StaffPortalShiftSwapListResponse

Example

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

POST

/api/v2/staff-portal/shift-swaps

Request a shift swap

Parameters

Name	In	Type	Required	Description
		string	no	—

Request body

StaffPortalShiftSwapCreateRequest

Response

StaffPortalShiftSwapMutationResponse

Example

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

PATCH

/api/v2/staff-portal/shift-swaps/{id}

Accept or decline a received shift swap

Parameters

Name	In	Type	Required	Description
		string	no	—
id	path	string (uuid)	yes	—

Request body

StaffPortalShiftSwapRespondRequest

Response

StaffPortalShiftSwapMutationResponse

Example

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

DELETE

/api/v2/staff-portal/shift-swaps/{id}

Cancel a requested shift swap while it is pending

Parameters

Name	In	Type	Required	Description
		string	no	—
id	path	string (uuid)	yes	—

Response

OkResponse

Example

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

GET

/api/v2/staff-portal/approval-policy

Get staff time-management approval policy

Parameters

Name	In	Type	Required	Description
		string	no	—

Response

StaffPortalApprovalPolicy

Example

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

PUT

/api/v2/staff-portal/approval-policy

Update staff time-management approval policy

Parameters

Name	In	Type	Required	Description
		string	no	—

Request body

object

Response

StaffPortalApprovalPolicy

Example

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

POST

/api/v2/staff-portal/session/handoff

Exchange a canonical staff portal handoff

Consumes a host-bound handoff once and returns an opaque adapter session handle.

Request body

object

Example

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

Plugin: feedback

POST

/api/v1/appointment-feedback

Submit feedback for an appointment

Requires an appointment-scoped feedback access token. A token and appointment must belong to the authenticated tenant.

Request body

SubmitAppointmentFeedbackRequest

Response

Feedback

Example

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

Plugin: waitlist

POST

/api/v1/waitlist

Join the booking waitlist

Creates an entry only when the requested service and optional staff member belong to the authenticated tenant.

Request body

CreateWaitlistEntryRequest

Response

WaitlistEntry

Example

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

Auth

POST

/api/v1/auth/signin

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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
active	query	string	no	Filter by active_for_sale status (defaults to true)[true, false]
category_id	query	string (uuid)	no	Filter by product category
updated_since	query	string (date-time)	no	Only 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

Name	In	Type	Required	Description
id	path	string	yes	Product 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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
start_at_gte	query	string (date-time)	no	Filter appointments starting on or after this timestamp
start_at_lte	query	string (date-time)	no	Filter appointments starting on or before this timestamp
status	query	string	no	Filter by appointment status[requested, confirmed, cancelled, completed, no_show]
location_id	query	string (uuid)	no	Filter by location ID
staff_id	query	string (uuid)	no	Filter by staff ID
service_id	query	string (uuid)	no	Filter by service ID
updated_since	query	string (date-time)	no	Only 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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
appointment_id	query	string (uuid)	no	Filter by appointment ID
updated_since	query	string (date-time)	no	Only 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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
is_active	query	string	no	Filter by active status[true, false]
updated_since	query	string (date-time)	no	Only 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

Name	In	Type	Required	Description
		string	no	—
		string	no	—
location_id	query	string (uuid)	no	Filter by location ID
service_id	query	string (uuid)	no	Filter by service ID
staff_id	query	string (uuid)	no	Filter by staff ID
created_at_gte	query	string (date-time)	no	Filter entries created on or after this timestamp
created_at_lte	query	string (date-time)	no	Filter 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 '{}'

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

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

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Webhook subscription ID

Response

OkResponse

Example

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

Plugin: referral

plugin

GET

/api/v1/referral/owner

Get or create the authenticated customer's referral code

Returns the referral code owned by the customer session supplied in `x-lumbu-customer-token`, creating it when needed. The tenant is derived from the tenant API key and the customer identity is verified in that tenant. Email query or body input is not accepted or used for authorization.

Parameters

Name	In	Type	Required	Description
		string	no	—

Response

ReferralOwnerCodeResponse

Example

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

GET

/api/v1/referral/validate

Validate a referral code format

Parameters

Name	In	Type	Required	Description
code	query	string	yes	Referral 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}"