For developers and integrators
The booking API for developers and agencies.
Availability, appointments, clients and payments, described in an OpenAPI contract. Build your own booking flow, add the widget to a website, or let an AI assistant prepare the configuration.
The sandbox is free and open to everyone. The public npm packages use the MIT licence.
Read these first
Authentication is a bearer token in the Authorization header. Every key carries explicit permissions, and a public widget key can only do what a visitor is allowed to do.
- https://sutempo.com/openapi.json : the complete OpenAPI description of the API, served under /v1
- https://sutempo.com/.well-known/platform-capabilities.json : the capability manifest of this deployment
- https://sutempo.com/llms.txt : the same summary, for an assistant
- https://sutempo.com/console : the developer console, with its sandbox, test keys and a three-step quick start
The shortest path to a booking
Read availability, place a hold while payment happens, then confirm. Slots are never computed on the client: the server only offers starts that are still in the future, and a hold stops two customers taking the same slot.
curl -H "Authorization: Bearer $SUTEMPO_KEY" \
"https://sutempo.com/v1/business-tenants/$TENANT/services"
curl -H "Authorization: Bearer $SUTEMPO_KEY" \
"https://sutempo.com/v1/business-tenants/$TENANT/availability/search?serviceId=$SERVICE&locationId=$LOCATION&from=2026-10-01&to=2026-10-07"
curl -X POST -H "Authorization: Bearer $SUTEMPO_KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
-d '{"locationId":"...","serviceId":"...","resourceId":"...","startsAt":"2026-10-01T09:00:00Z"}' \
"https://sutempo.com/v1/business-tenants/$TENANT/appointments/hold"The MCP server
The MCP server exposes a business's configuration as tools an agent can call. It does not read or change bookings, clients or payments, and it installs with npx -y @sutempo/mcp. The contract makes preview mandatory before apply: an agent reads the configuration, proposes a change, shows its effects, and only then applies it.
That is not a formality. The preview returns the list of destructive changes, and the apply is refused if the configuration moved between the two calls.
- describe_capabilities, list_business_tenants, list_tenant_modules: what this deployment can do
- get_current_blueprint, get_blueprint_version: the current state and its version
- preview_blueprint_changes then apply_blueprint_changes: propose, then apply
- schedule_group_sessions, cancel_group_session: group classes
- get_translation_status, set_translation_override: the languages of the public page
Putting booking inside a site
Two routes, depending on what you are building. The embeddable widget drops into an existing site with a public key and inherits the page's language. The JavaScript SDK and the underlying API let you build the whole flow yourself, payment included.
Either way, payments go to the business's Stripe account, never to an intermediary.
<script src="https://sutempo.com/widget.js"
data-key="pk_…" data-mode="modal"></script>
<button data-platform-widget-open>Book</button>JavaScript SDK and custom booking flows
Install @sutempo/sdk with npm: it provides one method per OpenAPI operation and is regenerated with the contract. Use @sutempo/booking-flow to build your own interface, with no required HTML or CSS.
npm i @sutempo/sdkPay to manage businesses, not to call the API.
Your developer account counts the businesses active at the same time. Archiving a business frees up its place. Every plan includes the sandbox, console, keys and webhooks.
On a real business, API access requires that business’s Pro plan and its owner’s revocable authorisation. The business pays its own Pro subscription (€29 excluding VAT per month per venue), not the developer.
| Plan | Monthly price | Active businesses |
|---|---|---|
| Free | €0 | Up to 3 |
| Agency | €49 excluding VAT | Up to 20 |
Create a developer account · Ask about the Agency plan · Business pricing
Security and reliability
- Keys carry explicit permissions and assigned businesses, are stored as hashes and are displayed only once.
- Outgoing webhooks are signed with HMAC-SHA256 over the timestamp and body; destinations must use HTTPS.
- Quotas apply per key, per business and globally. Exceeding a limit returns 429 with Retry-After.
- The application runs on Vercel and the database on Neon, in the Frankfurt region.
Frequently asked questions
Is the API charged separately?
The sandbox is free. Developer pricing depends on how many active businesses you manage: Free includes up to 3; Agency costs €49 excluding VAT a month for up to 20. Each real business must separately have Pro (or a Pro trial) and authorise your access. There is no charge per API call.
How do I get a key?
Create a developer account from the console: a sandbox opens at once, with a demo business on fictitious data and test keys, no invitation needed. For a real business, its owner on Pro authorises you from their workspace (Settings, Developer access) with your email address, and you collect the key in the console. They can remove that access at any time.
What can I do in the sandbox?
Everything the API allows on a Pro business, on fictitious data: services, people, opening hours, clients, bookings, webhooks. No email is sent, nothing is charged and the page is never published. By default, one sandbox per account, ten active keys, three businesses and 60 requests per minute.
Are writes idempotent?
Yes. Writes accept an Idempotency-Key header, which makes a retry after a network failure safe.
Can the MCP server change a business without oversight?
No. The contract requires a preview call before an apply, and the apply fails if the configuration changed in between.
Are there webhooks?
Yes. Webhook delivery is part of the platform and is configured like the rest, through the API.
Your first call in five minutes.
Create a developer accountA free developer account and test keys for a fictitious business: no real emails or payments.