REST API Access Guide

1. What's included

PRO workspaces can issue a one-time API access key to call ShiftScheduler's built-in REST endpoints directly. The key authenticates requests to the same server-side routes that power the web application, so you always receive normalized JSON responses.

2. Generating the API access key

1. Sign in and open Settings → API access for REST clients.
2. Click Generate new key.
3. Copy the one-time value that appears in the dialog. The plaintext key is never shown again.
4. Store it securely (we recommend a secrets manager). You can revoke or regenerate the key at any time from the same screen.

Only one API access key can exist per workspace. Regenerating a key immediately invalidates the previous value.

3. Authentication

All API requests must include the key in the Authorization header using the Bearer scheme:

curl https://shiftscheduler.ai/api/persons \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>"

• The key encodes your workspace ID, so every request is scoped to your workspace automatically.
• Keys are currently unlimited; apply your own rate limiting if you expose the key to client-side apps.

4. Supported endpoints

The following endpoints accept bearer authentication. Payloads use camelCase fields, and responses always return the normalized ShiftScheduler shape.

| Method | Endpoint | Notes |
| ------ | -------- | ----- |
| GET | `/api/persons` | List all persons in the workspace. |
| POST | `/api/persons` | Create a new person. |
| PUT | `/api/persons/{id}` | Update a person (partial updates supported). |
| DELETE | `/api/persons/{id}` | Delete a person and its shifts. |
| GET | `/api/locations` | List all locations. |
| POST | `/api/locations` | Create a location. |
| PUT | `/api/locations/{id}` | Update a location. |
| DELETE | `/api/locations/{id}` | Delete a location and its shifts. |
| PUT | `/api/location-day-schedules` | Update one location schedule, or multiple with an `items` array. |
| GET | `/api/shifts` | Optional filters: `locationId`, `personId`, `from`, `to`. |
| POST | `/api/shifts` | Create one shift, or multiple with an `items` array. |
| PUT | `/api/shifts/{id}` | Update date range, hours, note, or links. |
| DELETE | `/api/shifts` | Remove one schedule item with `{ id }`, or multiple with `{ items: [{ id }] }`. |
| PUT | `/api/person-preferences` | Set or clear one preference, or multiple with an `items` array. |
| POST | `/api/timeoff/requests` | Create one Time Off request, or multiple with an `items` array. |
| PUT | `/api/timeoff/requests/{id}` | Update or approve one Time Off request. |

Collection write endpoints accept either their existing single-item payload or an explicit { items: [...] } envelope. Batch responses preserve input order and include success, failure, and mutation counts. Accepted batches return HTTP 200 even when an individual item fails.

Filtering shifts

GET /api/shifts accepts optional locationId, personId, from, and to query parameters to refine the list. Provide a single date to fetch everything on/after or on/before that day, or pass both to limit results to a window. When no filters are provided, you receive every shift in the workspace.

5. Creating data

Write endpoints accept the same payloads the web app uses internally. The examples below demonstrate how to create each entity with typical fields.

Create a person

curl -X POST https://shiftscheduler.ai/api/persons \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Jordan Weaver",
        "email": "jordan.weaver@example.com",
        "invited": true,
        "membership": {
          "role": "member"
        }
      }'

Set invited=true to trigger an email invitation. The server sanitises any membership payload before persisting.

To add someone without inviting them yet, omit invited (or set it to false) and skip the membership block—the person will be created without any access assigned.

Membership roles are supported. If you include membership, you can set role (admin, manager, or member) and optional status (one of pending, active, inactive, or declined).

Responses include the normalised membership snapshot (status, invite email, and timestamps) so you can confirm what was persisted.

Create a location

curl -X POST https://shiftscheduler.ai/api/locations \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Website Relaunch",
        "color": "#2563eb",
        "note": "Public roadmap initiative"
      }'

Create an shift

curl -X POST https://shiftscheduler.ai/api/shifts \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "location": "PROJECT_ID",
        "person": "PERSON_ID",
        "date": "2025-10-20",
        "startTime": "09:00",
        "endTime": "17:00",
        "note": "Internal workshop prep and handoff"
      }'