Zaptime for developers

Zaptime is an online booking calendar from the Czech Republic. This developer portal collects everything you need to build on it: the public booking API, the embeddable calendar, webhooks, the MCP server for AI assistants and the machine-readable files agents can read. Human-readable guides live at docs.zaptime.app.

Quickstart: Zaptime API in three requests

Sign up at my.zaptime.app/register (the Personal plan is free) and create an event type.
Open my.zaptime.app/calendars, pick the event type and copy its API token. The token is the API key: every event type has its own.
Read available time slots and create a reservation:

# Available slots
curl "https://api.zaptime.app/time-slots?from=2026-09-01&until=2026-09-07" \
  -H "Authorization: Bearer $ZAPTIME_TOKEN" -H "Accept: application/json"

# Book one of them
curl -X POST https://api.zaptime.app/reservations \
  -H "Authorization: Bearer $ZAPTIME_TOKEN" -H "Content-Type: application/json" \
  -d '{"start":"2026-09-01T09:00:00Z","end":"2026-09-01T09:30:00Z","email":"[email protected]","firstname":"Jane","lastname":"Doe","timezone":"Europe/Prague"}'

The full request and response shapes are in the OpenAPI 3.1 specification (11 operations: time slots, reservations, prepare and confirm flow, payments, event type configuration, timezones).

Sandbox and testing

There is no separate sandbox host. Create a dedicated test event type in your account (for example "API test") and use its token; reservations made against it are real bookings in that calendar only and can be cancelled through the API. Disabled event types return 403 event_type_disabled, which is a quick way to turn a test integration off.

Authentication

Send the event type token as a bearer token: Authorization: Bearer <token>. Tokens are scoped to one event type and can be regenerated in the app at any time. GET /timezones needs no token. Missing or invalid tokens return 401 unauthenticated.

Errors

Every error is JSON, never an HTML page, even without an Accept header. The body is the Error schema from the OpenAPI spec:

{
  "success": false,
  "status": 404,
  "code": "not_found",
  "message": "Not found.",
  "hint": "Check the path and resource identifier. Endpoints are listed in the OpenAPI spec.",
  "docs": "https://zaptime.cz/developers/#errors"
}

HTTP	`code`	When
400	`bad_request`, `unsupported_api_version`	Malformed request or unknown `Zaptime-Api-Version`
401	`unauthenticated`	Missing or invalid bearer token
403	`forbidden`, `event_type_disabled`	Token is valid but the event type is disabled
404	`not_found`	Unknown path or reservation UUID
405	`method_not_allowed`	Wrong HTTP method
422	`validation_failed`	Invalid input; `errors` lists messages per field
429	`rate_limited`	Rate limit exceeded; wait `Retry-After` seconds
200 with `success: false`	`slot_locked`, `reservation_finished`	Someone else is booking the slot, or the reservation can no longer be refreshed
400	`stripe_not_configured`	Payment requested on an event type without Stripe
422	`payment_required`	Confirmation attempted before a successful payment
500	`internal_error`	Unexpected failure; retry, then contact support

Branch on code, not on message: codes are stable, messages may be reworded.

Rate limits

60 requests per minute per token (per IP without a token). Every response carries the IETF rate-limit headers plus the legacy X-RateLimit-* pair:

RateLimit-Policy: 60;w=60
RateLimit: limit=60, remaining=59, reset=60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

A 429 adds Retry-After (seconds). Back off for that long and retry.

Versioning and deprecation policy

The API is version 1. Paths are not versioned; each response carries Zaptime-Api-Version: 1, and you may pin the version by sending the same request header (unknown values return 400 unsupported_api_version). Within a version changes are additive only: new endpoints, optional parameters and response fields. Breaking changes ship as a new version. Anything being retired is announced on this page and in the release notes at least 6 months ahead, and the affected responses carry Deprecation and Sunset headers (RFC 9745 and RFC 8594) during that period.

Embeddable calendar and SDKs

Script tag or iframe: Getting started
Vue 3: @zaptime/vue3 on npm, installation guide and headless composables
Framework-agnostic logic: @zaptime/core on npm
Configuration reference: ZaptimeConfig, locale, theme

Webhooks

Zaptime calls your URL when a reservation is created, rescheduled or cancelled. Configure the URL per event type in the app; payloads and retry rules are in the webhooks guide.

MCP server for AI assistants

Zaptime ships an MCP (Model Context Protocol) server so ChatGPT, Claude and other assistants can list event types, resolve booking links, search, reschedule and cancel reservations and manage availability. Setup instructions and the tool list are on Zaptime MCP.

Command line

There is no official Zaptime CLI yet. The API is plain HTTPS and JSON, so curl plus the OpenAPI spec (or a client generated from it with openapi-generator) covers scripting needs. Want one? Tell us at [email protected].

Machine-readable resources

OpenAPI specification
llms.txt and llms-full.txt
Every page is also markdown: append .md to the path or send Accept: text/markdown
Sitemap
API status

Support

Email [email protected]. Include the request path, the code from the error body and, if you have it, the apigw-requestid response header.