← WebScheduler home   ← API reference

WebScheduler API: Getting started

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.

1. Get an API key

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.

2. Authenticate every request

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/appointments

3. Read the response envelope

Successful 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." } } }

4. Common error codes

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.

5. Pagination, sorting, search

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=ada

6. Rate limits

Each key is limited to 120 requests per 60 seconds. Exceeding it returns 429 with a Retry-After header (seconds to wait).

Full reference

Browse every endpoint, schema and example in the interactive API reference, or download the OpenAPI spec.