Open API

Developer

Build your own integrations — read schedules, shifts, staff and time entries over a simple REST API.

Who can use this: business owners and account admins can create and manage API keys under Settings → Integrations. The key can then be used by any tool or script you trust.

What you can do

The Simple Planning API is a read-only REST API (JSON) that lets your own tools and third-party services read your planning data. Four core resources are available:

Schedules
Published weekly schedules
Shifts
Individual shifts, with staff and location
Staff
Your team members and their basics
Time entries
Clock-in / clock-out records

Getting started

1Go to Settings → Integrations and open API keys.
2Create a key: give it a name and pick the scopes it needs (see below).
3Copy the key — it starts with sp_live_ and is shown only once. Store it somewhere safe.
4Send it on every request in the X-API-Key header.

The raw key is displayed exactly once at creation. We only store a hash, so if you lose it you'll need to revoke and generate a new one.

Authentication

Every /v1 request must include your key in the X-API-Key header:

X-API-Key: sp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL: https://sqrpbxpodbukvnjulmhd.supabase.co/functions/v1/api

Scopes

Each key carries a set of scopes, and each endpoint requires one. Request only what you need — a missing scope returns 403.

Scope	Grants access to
`schedules:read`	Published schedules (and their nested shifts)
`shifts:read`	Individual shifts from published schedules
`staff:read`	Staff members and their basic details
`time_entries:read`	Clock-in / clock-out time entries

Endpoints

Endpoint	Scope	What it returns
`GET /health`	`—`	Simple status check, no key required.
`GET /v1/schedules`	`schedules:read`	Published schedules, newest week first. Filter by week_start.
`GET /v1/schedules/:id`	`schedules:read`	One schedule with all its shifts nested (staff + location joined).
`GET /v1/shifts`	`shifts:read`	Shifts from published schedules. Filter by date, from/to, staff_id, location_id, status.
`GET /v1/shifts/:id`	`shifts:read`	A single shift.
`GET /v1/staff`	`staff:read`	Staff, alphabetical. Active by default; pass is_active=false for inactive.
`GET /v1/staff/:id`	`staff:read`	A single staff member.
`GET /v1/time_entries`	`time_entries:read`	Time entries, newest clock-in first. Filter by staff_id, shift_id, from/to.
`GET /v1/time_entries/:id`	`time_entries:read`	A single time entry.

Responses & pagination

List endpoints wrap results in a data array plus a pagination object. Use limit (default 25, max 100) and offset to page through larger sets.

{
  "data": [ ... ],
  "pagination": { "total": 132, "limit": 25, "offset": 0 }
}

Errors use a consistent envelope: { "error": { "code", "message" } } with codes like unauthorized, forbidden, not_found and rate_limited.

Rate limits

The API allows 60 requests per minute per key. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset so you can pace your calls; going over returns 429.

Example

Fetch every published shift for a week:

curl -H "X-API-Key: sp_live_..." \
  "https://sqrpbxpodbukvnjulmhd.supabase.co/functions/v1/api/v1/shifts?from=2026-08-17&to=2026-08-23&limit=100"

Or one schedule with its shifts nested:

curl -H "X-API-Key: sp_live_..." \
  "https://sqrpbxpodbukvnjulmhd.supabase.co/functions/v1/api/v1/schedules/<id>"

Good to know

Read-only — there are no write endpoints yet.
No webhooks — consumers poll for changes.
Only the four core resources are exposed (no leave, swaps or sections endpoints yet).
Only published schedules are visible; drafts stay private.

Frequently asked questions

Need a key or have questions?

Create keys under Settings → Integrations, or reach out to support@simpleplanning.works if you'd like help building your integration.