Skip to content

Read the organization

GET
/api/v1/organization

The calling organization's own profile and settings, and the operation that makes the rest of the API navigable: businessType is how a program learns which engine it is talking to, and so which set of endpoints applies. Shared, so it answers for both engines.

A singleton: the envelope is { data: { … } } with an object, and there is no nextCursor, limit or cursor. Every v1 response is still unwrapped the same way, from data.

timezone is the organization's IANA zone. The wall-clock times on GET /api/v1/service-periods are expressed in it, and startsAt/endsAt on bookings carry its offset for their date. currency and the deposit* fields are what a program needs to quote a deposit without guessing.

There is deliberately no organization:write scope: the slug, status and engine are not something a long-lived, program-held credential should be able to change.

Authorization

bearerApiKey organization:read
AuthorizationBearer <token>

Build with a test key (sk_test_...): it works only in your API sandbox and never emails or texts anyone. Scopes, errors and limits.

In: header

Scope: organization:read

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/organization"
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "slug": "string",    "industry": "string",    "status": "string",    "timezone": "string",    "businessType": "appointments",    "tagline": "string",    "currency": "string",    "logoUrl": "string",    "backgroundImageUrl": "string",    "accentColor": "string",    "bookingTheme": "string",    "bookingThemeToggleEnabled": true,    "notifyEmailEnabled": true,    "notifySmsEnabled": true,    "depositEnabled": true,    "depositType": "fixed",    "depositAmountCents": 0,    "depositPercentage": 0,    "depositPerPerson": true,    "depositMinPartySize": 0,    "depositRefundWindowHours": 0,    "guestManageEnabled": true,    "guestManageCutoffHours": 0,    "createdAt": "2019-08-24T14:15:22Z"  }}

List clientsGET

The organization's client and guest directory. Shared by both engines, since a client record means the same thing to a salon and a restaurant, so there is no `wrong_vertical` failure here. Newest first. No date filters, because a directory is not time-shaped, and no search parameter: page through the whole list with `cursor`.

Find free timesGET

Free times at the key's own organization, from the same slot engine its booking page uses, so a time this returns is one `POST /api/v1/reservations` or `POST /api/v1/appointments` will accept (until someone else books it). **Shared**: the organization's engine decides the question. - A table-reservations venue: `date` and `partySize`. - An appointments business: `date` and `serviceId`, optionally `providerId` (omit it for any available team member; each slot then names the `providerId` it was found for). `days` walks forward from `date`, up to 14 days in one call. Each day carries its `slots` and, for a venue, the `reason` an empty day is empty (`closed`, `full`, `too_large` and so on), so a fully booked day and a closed one never look alike. **Appointment start times sit on one grid per day** (behaviour change, 2026-10-13): every `appointmentSlotMinutes` from the business's opening time that day, or from midnight when it has no opening hours. A team member whose hours start off that grid joins it at the next tick, so with any available team member the slots no longer mix, say, 9:00 and 9:10 starters. The public MCP's `find_appointment_times` answers from the same engine and changed the same way. **Slot times are the venue's wall clock wearing a `Z`**, exactly like `startsAt` on a booking. Send one back to create unchanged; never convert it, or it moves by the venue's whole offset. Also limited per calling IP, 240 requests a minute, by the booking page's own limiter: a `429` here can come from either limit, and both carry `Retry-After`.