# REST API

> Book and manage bookings over plain HTTP, and read your own business's bookings with an API key.

Canonical: https://bookwise.live/docs/public-api

MCP server version: 1.1.0

## Overview

The REST API at https://bookwise.live/api/v1 does what the MCP tools do, over plain HTTP and JSON. It uses the same services as the booking page, so availability, prices, policies and error codes are identical. The full contract is in the OpenAPI 3.1 document.

### OpenAPI document

```text
https://bookwise.live/api/v1/openapi.json
```

Businesses are addressed by ID (biz_…) or by their booking-page slug. Requests and responses are JSON; send content-type: application/json. Every endpoint allows cross-origin requests.

## Booking flow

| Step | Request |
| --- | --- |
| Business details and booking params schema | `GET /businesses/{business}` |
| Live availability | `POST /businesses/{business}/availability` with `{ params }` |
| Hold an option | `POST /businesses/{business}/holds` with `{ optionId, params, customer, idempotencyKey }` |
| Confirm with contact details | `POST /holds/{holdId}/confirm` with `{ customer, idempotencyKey }` |
| Verify the code, if one was sent | `POST /holds/{holdId}/verify` with `{ code }` |
| Read or cancel later | `GET /bookings/{bookingId}`, `POST /bookings/{bookingId}/cancel` with `Authorization: Bearer <accessToken>` |

Follow nextStep in each response: verification_required, payment_required (send the customer to paymentUrl), pending_approval (the business decides), or confirmed. Never collect card details yourself.

## Your own bookings

Owners create API keys in Dashboard → Settings → API keys. A key belongs to one business and can only read. Send it as Authorization: Bearer bw_…

| Request | Scope |
| --- | --- |
| `GET /owner/bookings?status=confirmed&from=2026-11-01T00:00:00Z` | bookings:read |
| `GET /owner/overview?days=30` | overview:read |

> **Keep keys secret**: A key is shown once when it's created. Revoke it from Settings if it leaks; anything using it stops working at once.

## Limits and errors

Requests are rate-limited per IP address: 60 reads, 10 holds and 5 confirmations a minute. Errors return the same codes as MCP (VALIDATION_ERROR, SLOT_UNAVAILABLE, HOLD_EXPIRED, RATE_LIMITED…) with an HTTP status, a message and, for invalid fields, the fields at fault. See Errors and retries.