REST API Access Guide

Zuletzt geprüft: 11. Oktober 2026

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.

Nur Arbeitsbereichsadministratoren dürfen Integrationsschlüssel verwalten. Die Organisation benötigt mindestens eine bezahlte Lizenz zum Erstellen oder Verwenden eines REST-API-Schlüssels; eine kostenlose Testphase reicht nicht aus. Schlüssel haben Administratorrechte innerhalb ihres Arbeitsbereichs.

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>"

Bei Server-zu-Server-Anfragen den Bearer-Schlüssel ohne Browser-Sitzungscookies senden. Eine gültige Browsersitzung hat Vorrang und verwendet deren Berechtigungen. Anfragen mit JSON-Inhalt benötigen Content-Type: application/json; Anfragen ohne Inhalt nicht.

Authentifizierungsfehler liefern 401. Ein gültiger Schlüssel ohne bezahlten Zugriff liefert 403. Berechtigungen und Lizenzlimits können ebenfalls 403 liefern; Konflikte 409 und ungültige Eingaben meist 400. Fehlerantworten enthalten die Zeichenfolge error. Eine bezahlte Lizenz umgeht keine organisationsweiten Personenlimits.

  • 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.

| Methode | Endpunkt | Hinweise |
| --- | --- | --- |
| GET, POST | `/api/persons` | Personen auflisten oder erstellen. |
| GET, PUT, DELETE | `/api/persons/{id}` | Person lesen, teilweise ändern oder mit abhängigen Datensätzen löschen. |
| POST | `/api/persons/reorder` | Mit orderedIds sortieren; bei alphabetischer Sortierung nicht verfügbar. |
| POST | `/api/persons/{id}/access` | Zugriff mit action verwalten: invite, cancel-invite oder revoke. Einladungen versenden E-Mails. |
| GET, POST | `/api/locations` | Standorte auflisten oder erstellen. |
| GET, PUT, DELETE | `/api/locations/{id}` | Standort lesen, ändern oder mit seinen Schichten löschen. |
| POST | `/api/locations/reorder` | Mit orderedIds sortieren; bei alphabetischer Sortierung nicht verfügbar. |
| GET, POST | `/api/shift-templates` | Arbeitsbereichsweite Vorlagen auflisten oder erstellen. |
| GET, PUT, DELETE | `/api/shift-templates/{id}` | Vorlage lesen, ändern oder löschen; Verweise können das Löschen verhindern (409). |
| POST | `/api/shift-templates/{id}` | Auswirkungen einer Vorlagenänderung ohne Speichern prüfen. |
| GET, PUT, DELETE | `/api/location-day-schedules` | GET: locationIds/locationId, from, to. PUT: locationId, date, slots. DELETE: Abfrageparameter locationId und date. |
| GET, POST, DELETE | `/api/shifts` | GET: locationId, personId, date, from, to. POST: erstellen. DELETE: JSON mit id. |
| PUT | `/api/shifts/{id}` | Schicht teilweise ändern. |
| GET, DELETE | `/api/schedule-draft` | Gemeinsamen Entwurf lesen; includeChanges=true ergänzt sichere Änderungsbeschreibungen. DELETE verwirft den gesamten Entwurf. |
| POST | `/api/schedule-draft/publish` | Alle ausstehenden Änderungen atomar veröffentlichen. |
| GET, PUT | `/api/person-preferences` | GET: personIds/personId, from, to. PUT: personId, date, preference; ein leerer Wert löscht die Präferenz. |
| GET, POST | `/api/timeoff/requests` | GET: status (Standard requested; archived umfasst approved/rejected). POST: personId, date, typeId; Stunden stammen aus der Vorlage. |
| PUT | `/api/timeoff/requests/{id}` | Notiz/Datum oder action: approve/reject ändern. Vorlage und Zeiten sind unveränderlich. |
| GET | `/api/timeoff/allowances` | Sichtbare Abwesenheitskontingente lesen. |
| GET, POST | `/api/timeoff/grants` | GET benötigt personId. POST: personId, typeId, hours, optional note. |
| DELETE | `/api/timeoff/grants/{id}` | Kontingentbuchung stornieren; der Prüfdatensatz bleibt bis zur Löschung der Person erhalten. |
| GET | `/api/overview` | Übersicht mit optionalen Datumswerten start/end. |
| GET, PUT | `/api/workspace/ai-settings` | KI-Regeln lesen; PUT ersetzt rules oder führt die unterstützte Regelaktion aus. |
| PATCH | `/api/workspace/rules/reset-interpretation` | Regelinterpretation mit ruleId zurücksetzen. |

Die Antwortfelder unterscheiden sich: persons, locations, shifts, schedules, preferences (mit quotas), data (Vorlagen und Abwesenheitsanträge), grants (mit summary) oder allowances. Es sind keine bloßen Arrays. Auch Schreibantworten unterscheiden sich je nach Endpunkt.

Nur POST /api/shifts, DELETE /api/shifts, PUT /api/location-day-schedules, PUT /api/person-preferences und POST /api/timeoff/requests unterstützen ein { items: [...] }.

Stapelergebnisse behalten die Eingabereihenfolge bei und enthalten successCount, failureCount, mutationCount und results. Akzeptierte Stapel liefern HTTP 200, selbst wenn einzelne oder alle Einträge fehlschlagen. Die Felder ok und status jedes Ergebnisses prüfen; HTTP 200 allein bedeutet keinen Erfolg.

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.

Änderungen an Personen, Standorten oder Vorlagen machen KI-Regelinterpretationen ungültig. Das Löschen von Personen oder Standorten entfernt abhängige Plandaten. Vorlagenänderungen können Übertragungsoptionen erfordern; zuerst die Auswirkungen prüfen. Schreiboperationen in einem Testarbeitsbereich ausprobieren.

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"
      }'