REST API Access Guide

Naposledy ověřeno: 11. října 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.

Integrační klíče mohou spravovat pouze administrátoři prostoru. Organizace musí mít alespoň jednu placenou licenci pro vytvoření nebo použití REST API klíče; samotná zkušební doba nestačí. Klíče mají v rámci svého prostoru práva administrátora.

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

Při komunikaci mezi servery posílejte Bearer klíč bez cookies relace prohlížeče. Platná relace má přednost a použije vlastní oprávnění. JSON tělo vyžaduje Content-Type: application/json; požadavek bez těla tuto hlavičku nepotřebuje.

Chyby ověření vracejí 401. Platný klíč bez placeného přístupu vrací 403. Oprávnění a limity licencí mohou také vracet 403; konflikty 409 a neplatné vstupy obvykle 400. Chyby obsahují řetězec error. Placená licence neobchází limity osob v celé organizaci.

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

| Metoda | Endpoint | Poznámky |
| --- | --- | --- |
| GET, POST | `/api/persons` | Vypsat nebo vytvořit osoby. |
| GET, PUT, DELETE | `/api/persons/{id}` | Načíst, částečně upravit nebo smazat osobu a související záznamy. |
| POST | `/api/persons/reorder` | Změnit pořadí pomocí orderedIds; není dostupné při abecedním řazení. |
| POST | `/api/persons/{id}/access` | Spravovat přístup pomocí action: invite, cancel-invite nebo revoke. Pozvánky odesílají e-mail. |
| GET, POST | `/api/locations` | Vypsat nebo vytvořit pracoviště. |
| GET, PUT, DELETE | `/api/locations/{id}` | Načíst, upravit nebo smazat pracoviště a jeho směny. |
| POST | `/api/locations/reorder` | Změnit pořadí pomocí orderedIds; není dostupné při abecedním řazení. |
| GET, POST | `/api/shift-templates` | Vypsat nebo vytvořit šablony pracovního prostoru. |
| GET, PUT, DELETE | `/api/shift-templates/{id}` | Načíst, upravit nebo smazat šablonu; odkazy mohou smazání zabránit (409). |
| POST | `/api/shift-templates/{id}` | Zobrazit dopad úpravy šablony bez uložení. |
| GET, PUT, DELETE | `/api/location-day-schedules` | GET: locationIds/locationId, from, to. PUT: locationId, date, slots. DELETE: parametry locationId a date. |
| GET, POST, DELETE | `/api/shifts` | GET: locationId, personId, date, from, to. POST: vytvořit. DELETE: JSON tělo s id. |
| PUT | `/api/shifts/{id}` | Částečně upravit směnu. |
| GET, DELETE | `/api/schedule-draft` | Načíst sdílený koncept; includeChanges=true přidá bezpečné popisy změn. DELETE zahodí celý koncept. |
| POST | `/api/schedule-draft/publish` | Atomicky zveřejnit všechny čekající změny. |
| GET, PUT | `/api/person-preferences` | GET: personIds/personId, from, to. PUT: personId, date, preference; prázdná hodnota preferenci smaže. |
| GET, POST | `/api/timeoff/requests` | GET: status (výchozí requested; archived zahrnuje approved/rejected). POST: personId, date, typeId; časy se přebírají ze šablony. |
| PUT | `/api/timeoff/requests/{id}` | Upravit poznámku/datum nebo action: approve/reject. Šablonu ani časy nelze měnit. |
| GET | `/api/timeoff/allowances` | Načíst dostupné zůstatky volna. |
| GET, POST | `/api/timeoff/grants` | GET vyžaduje personId. POST: personId, typeId, hours, volitelně note. |
| DELETE | `/api/timeoff/grants/{id}` | Stornovat příděl; auditní záznam zůstane do smazání osoby. |
| GET | `/api/overview` | Přehled s volitelnými daty start/end. |
| GET, PUT | `/api/workspace/ai-settings` | Načíst pravidla AI; PUT nahradí rules nebo provede podporovanou akci pravidla. |
| PATCH | `/api/workspace/rules/reset-interpretation` | Resetovat interpretaci pravidla pomocí ruleId. |

Pole odpovědí se liší: persons, locations, shifts, schedules, preferences (s quotas), data (šablony a žádosti o volno), grants (se summary) nebo allowances. Nejde o samostatná pole bez obálky. Liší se i odpovědi zápisových operací.

Pouze POST /api/shifts, DELETE /api/shifts, PUT /api/location-day-schedules, PUT /api/person-preferences a POST /api/timeoff/requests přijímají obálku { items: [...] }.

Výsledky dávky zachovávají pořadí a obsahují successCount, failureCount, mutationCount a results. Přijatá dávka vrací HTTP 200, i když některé nebo všechny položky selžou. Kontrolujte ok a status jednotlivých výsledků; samotné HTTP 200 neznamená úspěch.

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.

Změny osob, pracovišť nebo šablon zneplatní interpretace pravidel AI. Smazání osob či pracovišť smaže související data rozpisu. Úpravy šablon mohou vyžadovat volby propagace; nejprve zobrazte dopad. Zápisy zkoušejte v testovacím prostoru.

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