--- title: "Zaptime for developers: API, SDKs, webhooks and MCP" description: "Zaptime developer portal: booking API with OpenAPI spec, API tokens, error codes, rate limits, versioning policy, Vue SDK, webhooks and the MCP server for AI assistants." canonical: https://zaptime.cz/en/developers/ --- # 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](https://docs.zaptime.app/). ## [Quickstart: Zaptime API in three requests](#quickstart-zaptime-api-in-three-requests) 1. Sign up at [my.zaptime.app/register](https://my.zaptime.app/register) (the Personal plan is free) and create an event type. 2. Open [my.zaptime.app](https://my.zaptime.app/), pick the event type and copy its **API token**. The token is the API key: every event type has its own. 3. 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":"jane@example.com","firstname":"Jane","lastname":"Doe","timezone":"Europe/Prague"}'` The full request and response shapes are in the [OpenAPI 3.1 specification](https://zaptime.cz/openapi.json) (11 operations: time slots, reservations, prepare and confirm flow, payments, event type configuration, timezones). ## [Sandbox and testing](#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](#authentication) Send the event type token as a bearer token: `Authorization: Bearer `. 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](#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](#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](#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](https://zaptime.cz/novinky/) 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](#embeddable-calendar-and-sdks) - Script tag or iframe: [Getting started](https://docs.zaptime.app/guide/getting-started.html) - Vue 3: [`@zaptime/vue3`](https://www.npmjs.com/package/@zaptime/vue3) on npm, [installation guide](https://docs.zaptime.app/guide/vue-installation.html) and headless composables - Framework-agnostic logic: [`@zaptime/core`](https://www.npmjs.com/package/@zaptime/core) on npm - Configuration reference: [ZaptimeConfig](https://docs.zaptime.app/reference/zaptime-config.html), [locale](https://docs.zaptime.app/reference/zaptime-locale.html), [theme](https://docs.zaptime.app/reference/zaptime-theme.html) ## [Webhooks](#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](https://docs.zaptime.app/guide/webhooks.html). ## [MCP server for AI assistants](#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](https://zaptime.cz/en/features/mcp/). ## [Command line](#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 [support@zaptime.app](mailto:support@zaptime.app). ## [Machine-readable resources](#machine-readable-resources) - [OpenAPI specification](https://zaptime.cz/openapi.json) - [llms.txt](https://zaptime.cz/llms.txt) and [llms-full.txt](https://zaptime.cz/llms-full.txt) - Every page is also markdown: append `.md` to the path or send `Accept: text/markdown` - [Sitemap](https://zaptime.cz/sitemap.xml) - [API status](https://status.zaptime.app/) ## [Support](#support) Email [support@zaptime.app](mailto:support@zaptime.app). Include the request path, the `code` from the error body and, if you have it, the `apigw-requestid` response header.