Public booking API

Read a business's services and free time slots, and create a booking. These are the same endpoints the public booking page calls — no API key, no token, no registration. They are rate limited per IP exactly like the booking form.

Basics

Base URL: https://spotdrop.si
Machine-readable description: /openapi.json (OpenAPI 3.1)
All times are Europe/Ljubljana. Dates are YYYY-MM-DD, times HH:MM.
{slug} is the last path segment of a business page: spotdrop.si/frizerstvo-ana has slug frizerstvo-ana.

GET`/api/company/{slug}/appointment-services`

Services the business has enabled for online booking.

{ "services": [ { "id": 12, "name": "Moško striženje", "duration": 30, "price": "18" } ] }

name must be sent back verbatim when booking. duration is in minutes and belongs in the slots request. price is a string exactly as the business typed it.

GET`/api/company/{slug}/slots`

Query: date (required), duration (minutes, default 30), employeeId (optional).

{ "slots": [ { "time": "09:00", "available": true },
            { "time": "09:30", "available": false } ] }

Only available: true is bookable. An empty array is a normal answer — closed day, blocked date, or outside the business's booking window. Businesses that book per employee need employeeId, because availability differs per person.

POST`/api/company/{slug}/appointments`

{
  "serviceName": "Moško striženje",
  "guestName": "Ana Novak",
  "guestPhone": "+38641123456",
  "guestEmail": "[email protected]",
  "appointmentDate": "2026-09-01",
  "appointmentTime": "09:00",
  "source": "api"
}

Required: serviceName, guestName (min 2 characters), guestPhone (min 7 digits), appointmentDate, appointmentTime. Optional: guestEmail (recommended — it carries the confirmation and the cancellation link), employeeId, notes, lang, source.

When the service requires a deposit the response carries requiresPayment: true with a checkoutUrl and status pending_payment. The slot is held only until that Stripe checkout is paid — pass the URL to the customer and do not report the appointment as confirmed.

409 means the slot was taken in the meantime: re-read availability and offer another time.

For AI agents

/.well-known/api-catalog — RFC 9727 catalog
/.well-known/ai-catalog.json — ARD capability manifest
/.well-known/agent-skills/index.json — booking and page-reading skills
/.well-known/mcp/server-card.json — MCP server at /api/mcp (read-only tools)
/auth.md — what needs authentication and what does not
Any page can be fetched with Accept: text/markdown; a business page is also at /md/{slug}.

Rules of use

Book only on behalf of a person who asked for that slot and gave you their details.
No speculative or duplicate bookings — a slot is a real slot in a real calendar.
Do not poll availability on a schedule; read it when someone asks.
Identify your client in the User-Agent header.

Dashboard endpoints (appointment lists, customers, schedules, billing) require a human login and are not machine-callable. If you need owner-level access, write to [email protected].