A REST API for integrating with your WebScheduler instance: create appointments, read availability, and manage customers, services and providers.
WebScheduler is self-hosted, so your API base is your own
instance domain. Replace https://your-webscheduler-domain
in the examples below with the domain where WebScheduler is installed.
Keys are per-user and issued from the server CLI. The full token is shown once and cannot be recovered afterwards.
php spark api:key create --user <userId> --name "Zapier production"The request runs with the bound user's roles, so a key used to create providers or edit business hours must belong to an admin.
Send the token as a Bearer credential. There is no shared secret and no API key in query strings.
curl -H "Authorization: Bearer xsk_ab12cd34ef56_XXXXXXXX…" \
https://your-webscheduler-domain/api/v1/appointmentsSuccessful responses wrap the payload in data, with optional
meta (pagination, timestamps):
{ "data": { ... }, "meta": { "page": 1, "per_page": 25, "total": 42 } }Errors return a stable machine-readable code:
{ "error": { "message": "Validation failed", "code": "VALIDATION_ERROR",
"details": { "email": "Email address is not valid." } } }| HTTP | code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing or invalid token. |
| 403 | forbidden | Token's user lacks the required role. |
| 422 | VALIDATION_ERROR | Payload failed validation (see details). |
| 429 | rate_limited | Too many requests — see Retry-After. |
List endpoints accept page, length (max 100),
sort (field:asc|desc) and, where supported,
q for free-text search.
GET https://your-webscheduler-domain/api/v1/customers?page=2&length=50&sort=created_at:desc&q=adaEach key is limited to 120 requests per 60 seconds.
Exceeding it returns 429 with a Retry-After
header (seconds to wait).
Browse every endpoint, schema and example in the interactive API reference, or download the OpenAPI spec.