REST API for Shift Scheduling Automation

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.

Seuls les administrateurs de l’espace peuvent gérer les clés. L’organisation doit disposer d’au moins une licence payante pour générer ou utiliser une clé API REST ; l’essai gratuit seul ne suffit pas. Les clés disposent de droits équivalents à ceux d’un administrateur dans leur espace.

2. Generating the API access key

Sign in and open Settings → API access for REST clients.
Click Generate new key.
Copy the one-time value that appears in the dialog. The plaintext key is never shown again.
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>"

Pour les requêtes entre serveurs, envoyer la clé Bearer sans cookies de session du navigateur. Une session valide est prioritaire et impose ses permissions. Un corps JSON nécessite Content-Type: application/json ; une requête sans corps ne le nécessite pas.

Les échecs d’authentification renvoient 401. Une clé valide sans accès payant renvoie 403. Les permissions et limites de licences peuvent aussi renvoyer 403 ; les conflits 409 et les données invalides généralement 400. Les erreurs contiennent une chaîne error. Une licence payante ne contourne pas les limites de personnes de l’organisation.

The key encodes your workspace ID, so every request is scoped to your workspace automatically.
API keys have workspace-wide access and are intended only for server-to-server use. Never expose a key in browser or mobile-app code.
Requests are not currently subject to a per-key rate limit, so apply appropriate rate limiting in your integration.

Getting locations

Use the REST API access key—not an MCP key or webhook secret. The response is a JSON object whose locations property is the array of locations; it is not a bare array.

curl https://shiftscheduler.ai/api/locations \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Accept: application/json"

{
  "locations": [
    {
      "id": "66f01234567890abcdef1234",
      "title": "Ward A",
      "sortOrder": 1,
      "weeklyTemplate": []
    }
  ]
}

Collection reads use matching envelopes: persons, locations , or shifts. A missing, invalid, revoked, or regenerated key returns 401 with a JSON error message.

4. Supported endpoints

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

| Méthode | Point d’accès | Notes |
| --- | --- | --- |
| GET, POST | `/api/persons` | Lister ou créer des personnes. |
| GET, PUT, DELETE | `/api/persons/{id}` | Lire, modifier partiellement ou supprimer une personne et ses données dépendantes. |
| POST | `/api/persons/reorder` | Réordonner avec orderedIds ; indisponible avec le tri alphabétique. |
| POST | `/api/persons/{id}/access` | Gérer l’accès avec action : invite, cancel-invite ou revoke. Les invitations envoient un e-mail. |
| GET, POST | `/api/locations` | Lister ou créer des lieux. |
| GET, PUT, DELETE | `/api/locations/{id}` | Lire, modifier ou supprimer un lieu et ses shifts. |
| POST | `/api/locations/reorder` | Réordonner avec orderedIds ; indisponible avec le tri alphabétique. |
| GET, POST | `/api/shift-templates` | Lister ou créer des modèles communs à l’espace de travail. |
| GET, PUT, DELETE | `/api/shift-templates/{id}` | Lire, modifier ou supprimer un modèle ; des références peuvent empêcher sa suppression (409). |
| POST | `/api/shift-templates/{id}` | Prévisualiser l’impact d’une modification du modèle sans enregistrer. |
| GET, PUT, DELETE | `/api/location-day-schedules` | GET : locationIds/locationId, from, to. PUT : locationId, date, slots. DELETE : paramètres locationId et date. |
| GET, POST, DELETE | `/api/shifts` | GET : locationId, personId, date, from, to. POST : créer. DELETE : corps JSON avec id. |
| PUT | `/api/shifts/{id}` | Modifier partiellement un shift. |
| GET, DELETE | `/api/schedule-draft` | Lire le brouillon partagé ; includeChanges=true ajoute des descriptions sûres des changements. DELETE supprime tout le brouillon. |
| POST | `/api/schedule-draft/publish` | Publier toutes les modifications en attente de façon atomique. |
| GET, PUT | `/api/person-preferences` | GET : personIds/personId, from, to. PUT : personId, date, preference ; une valeur vide efface la préférence. |
| GET, POST | `/api/timeoff/requests` | GET : status (requested par défaut ; archived inclut approved/rejected). POST : personId, date, typeId ; les horaires viennent du modèle. |
| PUT | `/api/timeoff/requests/{id}` | Modifier note/date ou action : approve/reject. Le modèle et les horaires sont immuables. |
| GET | `/api/timeoff/allowances` | Lire les soldes de congés visibles. |
| GET, POST | `/api/timeoff/grants` | GET nécessite personId. POST : personId, typeId, hours, note facultative. |
| DELETE | `/api/timeoff/grants/{id}` | Annuler une attribution ; la trace reste conservée jusqu’à la suppression de la personne. |
| GET | `/api/overview` | Vue d’ensemble avec dates start/end facultatives. |
| GET, PUT | `/api/workspace/ai-settings` | Lire les règles IA ; PUT remplace rules ou effectue l’action de règle prise en charge. |
| PATCH | `/api/workspace/rules/reset-interpretation` | Réinitialiser l’interprétation avec ruleId. |

Les champs de réponse varient : persons, locations, shifts, schedules, preferences (avec quotas), data (modèles et demandes de congés), grants (avec summary) ou allowances. Ce ne sont pas des tableaux bruts. Les réponses aux écritures varient aussi selon le point d’accès.

Seuls POST /api/shifts, DELETE /api/shifts, PUT /api/location-day-schedules, PUT /api/person-preferences et POST /api/timeoff/requests acceptent une { items: [...] }.

Les résultats de lot respectent l’ordre d’entrée et contiennent successCount, failureCount, mutationCount et results. Un lot accepté renvoie HTTP 200 même si certains ou tous les éléments échouent. Vérifier ok et status pour chaque résultat ; HTTP 200 seul ne garantit pas le succès.

Time Off responses include createdAt, the daily request order, and approval or rejection audit references. Queue order spans pending, approved, and rejected requests for the same calendar day.

If Draft Schedule is enabled for the workspace, API shift reads and regular-shift writes use the shared working schedule. Writes do not notify members or emit shift webhooks until the draft is published. Publishing applies every pending change together; deleting the draft discards it in full. Time Off operations remain immediate, and API keys have admin-equivalent permission to publish or discard.

To review the shared draft without exposing raw shift snapshots, call GET /api/schedule-draft?includeChanges=true. The optional changes array contains the operation type, document ID, label, and localized history descriptor parameters for each pending shift, ordered by schedule date.

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.

Les modifications de personnes, lieux ou modèles invalident les interprétations des règles IA. Supprimer des personnes ou lieux supprime les données de planning dépendantes. Les modifications de modèles peuvent nécessiter des options de propagation ; prévisualiser leur impact. Utiliser un espace de test pour essayer les écritures.

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",
        "invited": false
      }'

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 settings require invited=true and a valid email. The optional membership.role may be admin, manager , or member; it defaults to member. Supplying membership settings without requesting an invitation returns a validation error.

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": "Ward A",
        "weeklyTemplate": []
      }'

Create a shift

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

REST API Access Guide