Bookings API

A REST API for checking availability and creating, editing, rescheduling and cancelling appointments in real time. It is built to be driven by an AI agent: every failure is a stable machine-readable code, and when a time is taken the response hands back alternative slots so your agent can re-offer without another round trip.

Getting started

1. Sign in and open Dashboard → API keys.
2. Create a key, choose its permissions, and copy it — it is shown once.
3. Send it on every request as a bearer token.

curl https://otterflow.ph/api/v1/me \
  -H "Authorization: Bearer ofk_EXAMPLE_KEY_DO_NOT_USE"

GET /api/v1/me is the right first call. It returns the business timezone, the current server time, your key's permissions, the live rate limits and the datetime rules — everything an agent needs before it does anything real.

Authentication and permissions

Authorization: Bearer ofk_…, or X-OtterFlow-Key: ofk_… if a bearer header is awkward in your stack. Never put a key in the query string — that request will be rejected, because query strings end up in server access logs and in Referer headers.

Grant the least you need. Without customers:read you can still read bookings, but customer names and phone numbers come back masked ("Juan D.", "•••• ••• 4567") and searching by phone is refused. That is usually the right setting for an agent that only creates bookings.

Dates and times

This is where integrations most often go wrong, so the rule is strict: a time must name exactly one instant. Two forms are accepted.

"start": "2026-08-20T14:30:00+08:00"          // ISO 8601 with an offset
"start": "2026-08-20T06:30:00Z"               // …or Z
"start": { "date": "2026-08-20", "time": "14:30" }    // business-local
"start": { "date": "2026-08-20", "time": "2:30 PM", "tz": "Asia/Manila" }

These are rejected, on purpose:

Every timestamp we return carries all four readings, so you never have to format a date yourself:

{ "utc":   "2026-08-20T06:30:00Z",
  "local": "2026-08-20T14:30:00+08:00",
  "tz":    "Asia/Manila",
  "label": "Thu, Aug 20, 2:30 PM" }

Endpoints

There is no /customers endpoint. This system has no separate customer record — a customer's history is GET /api/v1/bookings?phone=…, which is why customers:read gates a filter rather than a resource.

Making a booking

Find a slot, then book the exact start.utc value it gave you.

curl "https://otterflow.ph/api/v1/availability?service_id=4&from=2026-08-20&to=2026-08-22" \
  -H "Authorization: Bearer ofk_EXAMPLE_KEY_DO_NOT_USE"

curl -X POST https://otterflow.ph/api/v1/bookings \
  -H "Authorization: Bearer ofk_EXAMPLE_KEY_DO_NOT_USE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ea2b-4c1f-9f2a-1d3c5b7a9e01" \
  -d '{
    "service_id": 4,
    "start": "2026-08-20T14:30:00+08:00",
    "client": { "name": "Juan Dela Cruz", "phone": "09171234567" },
    "notes": "First visit"
  }'

Always send an Idempotency-Key on writes. Networks fail between "booking created" and "response received". With a key, the retry replays the original response; without one, it books a second appointment. Reusing a key with a different body is an error rather than a silent replay of the wrong thing.

Email is optional — omit it if you don't have one. Please don't invent an address: a fabricated one looks real to the business and silently swallows mail. Phone is required whenever the service sends SMS; check requires.client_phone on the service.

Errors

Every failure has the same shape, with a stable error code to branch on:

{ "ok": false,
  "error": "slot_taken",
  "message": "That time is already booked.",
  "requested": { "utc": "…", "local": "…", "tz": "…", "label": "…" },
  "alternatives": [ { "utc": "…", "label": "Thu, Aug 20, 3:00 PM" } ],
  "next_available": { "utc": "…", "label": "Thu, Aug 20, 3:00 PM" } }

That last distinction matters. A 409 means the time is genuinely gone; a 503 means we couldn't take the write lock in time. Treating a 503 as "taken" would push a customer off a slot they could have had.

Why a day has nothing free

Empty days in an availability response carry a reason: closed (that weekday isn't worked), time_off (the business is away), fully_booked, past, or beyond_horizon. Read it before you tell a customer there's "nothing available" — "we're closed Sundays" is a different conversation.

Booking states

A booking is pending, confirmed, cancelled or rejected. Services with approval enabled start at pending. Always read status off the response rather than assuming.

• Cancelling something already cancelled returns 200 with changed: false, so a retry is safe.
• Rescheduling a pending booking leaves it pending — it is not an approval.
• Cancelled bookings cannot be rescheduled. Create a new one.
• There is no cancellation deadline. If you need one, enforce it in your own agent.

Limits

Roughly 120 requests and 20 writes per minute, and a daily cap on bookings created through the API. Live values for your key are in GET /me, and every response carries X-RateLimit-Remaining. Repeated bad keys are locked out for a while, so fix a 401 rather than retrying it.

Webhooks

Rather than polling, you can have booking events pushed to you: booking.created, booking.cancelled, booking.rescheduled, booking.approved, booking.rejected and booking.updated. They fire for every change — dashboard, customer link, chat or API — so your copy stays correct. Configure the URL in your dashboard; each delivery is HMAC-signed.

Wiring up an AI agent

Fetch the OpenAI bundle or the Anthropic one and hand the tools array straight to your model. The bundle also carries a system_guidance string worth putting in your system prompt — it encodes the rules agents most often break:

• Never invent a time. Call check_availability and use a slot it returned.
• Resolve "tomorrow" yourself from the business clock in get_business.
• On a 409, read alternatives and offer those.
• On a 503, retry the identical request.
• Never quote a price — this system doesn't store them.

approve and reject are deliberately left out of the tool bundles. An agent that can approve its own pending request defeats the point of asking for approval. They remain available over REST for a human's tooling.