Draft
Endpoints
Every v1 endpoint at a glance, with the most common request and response shapes.
The machine-readable contract lives in the repository at packages/openapi/openapi.yaml (OpenAPI 3.1).
Scheduling
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /slots | slots:read | Available slots for a service |
| POST | /holds | bookings:write | Create a 10-minute hold |
| POST | /holds/{id}/confirm | bookings:write | Confirm (or pending_payment if a deposit is required) |
| DELETE | /holds/{id} | bookings:write | Release a hold |
| GET | /bookings | bookings:read | List (filters: from, to, status, resource_id, customer_id) |
| POST | /bookings | bookings:write | Hold + confirm in one call |
| GET / PATCH | /bookings/{id} | bookings:read / write | Read, update notes or intake data |
| POST | /bookings/{id}/cancel | bookings:write | Cancel |
| POST | /bookings/{id}/reschedule | bookings:write | Move to a new start |
| POST | /bookings/{id}/check-in | bookings:write | Mark arrival |
| POST | /bookings/{id}/no-show | bookings:write | Mark absence |
Catalog
| Method | Path | Scope |
|---|---|---|
| GET / POST | /services | config:read / config:write |
| GET / POST | /resources | config:read / config:write |
| GET | /resource-groups | config:read |
| POST | /schedules/{id}/overrides | config:write |
Customers and conversations
| Method | Path | Scope |
|---|---|---|
| GET | /customers | customers:read |
| DELETE | /customers/{id} | customers:read + owner role (anonymizes, LGPD) |
| GET | /conversations | messages:read |
| GET / POST | /conversations/{id}/messages | messages:read / messages:write |
| POST | /conversations/{id}/handoff | messages:write |
Platform
| Method | Path | Scope |
|---|---|---|
| GET | /me | any |
| GET / POST | /webhook-endpoints | webhooks:manage |
| GET | /events | bookings:read |
Example: slots
GET /v1/slots?service_id=svc_laser&from=2026-10-20T09:00:00-03:00&to=2026-10-20T20:00:00-03:00&around=2026-10-20T18:00:00-03:00
{
"data": [
{ "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:30:00-03:00", "resource_ids": ["res_ana", "res_laser1", "res_room2"] },
{ "start": "2026-10-20T18:45:00-03:00", "end": "2026-10-20T19:30:00-03:00", "resource_ids": ["res_carla", "res_laser1", "res_room1"] }
],
"unavailable_reason": null
}
Example: booking object
{
"id": "bkg_7Qx1",
"status": "confirmed",
"service_id": "svc_laser",
"start": "2026-10-20T17:45:00-03:00",
"end": "2026-10-20T18:30:00-03:00",
"party_size": 1,
"customer": { "id": "cus_31", "name": "Marina", "phone": "+5521988887777", "locale": "pt" },
"allocations": [
{ "resource_id": "res_ana", "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:40:00-03:00", "units": 1 },
{ "resource_id": "res_laser1", "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:40:00-03:00", "units": 1 },
{ "resource_id": "res_room2", "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:40:00-03:00", "units": 1 }
],
"payment": { "status": "paid", "amount_cents": 5000 },
"source": "whatsapp",
"created_at": "2026-10-19T11:02:13-03:00"
}
Allocations include the buffer time (here 10 minutes after the service).