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.

Solo los administradores del espacio pueden gestionar claves. La organización necesita al menos una licencia de pago para generar o usar una clave API REST; la prueba gratuita no basta. Las claves tienen permisos de administrador dentro de su espacio.

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

Para solicitudes entre servidores, enviar la clave Bearer sin cookies de sesión del navegador. Una sesión válida tiene prioridad y usa sus permisos. Un cuerpo JSON requiere Content-Type: application/json; las solicitudes sin cuerpo no lo requieren.

Los fallos de autenticación devuelven 401. Una clave válida sin acceso de pago devuelve 403. Los permisos y límites de licencias también pueden devolver 403; los conflictos 409 y los datos inválidos normalmente 400. Los errores contienen una cadena error. La licencia no evita los límites de personas de la organización.

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étodo | Endpoint | Notas |
| --- | --- | --- |
| GET, POST | `/api/persons` | Listar o crear personas. |
| GET, PUT, DELETE | `/api/persons/{id}` | Leer, actualizar parcialmente o eliminar una persona y sus registros dependientes. |
| POST | `/api/persons/reorder` | Reordenar con orderedIds; no disponible con orden alfabético. |
| POST | `/api/persons/{id}/access` | Gestionar acceso con action: invite, cancel-invite o revoke. Las invitaciones envían correo. |
| GET, POST | `/api/locations` | Listar o crear ubicaciones. |
| GET, PUT, DELETE | `/api/locations/{id}` | Leer, actualizar o eliminar una ubicación y sus turnos. |
| POST | `/api/locations/reorder` | Reordenar con orderedIds; no disponible con orden alfabético. |
| GET, POST | `/api/shift-templates` | Listar o crear plantillas del espacio de trabajo. |
| GET, PUT, DELETE | `/api/shift-templates/{id}` | Leer, actualizar o eliminar una plantilla; las referencias pueden impedir la eliminación (409). |
| POST | `/api/shift-templates/{id}` | Previsualizar el impacto de cambios en la plantilla sin guardar. |
| GET, PUT, DELETE | `/api/location-day-schedules` | GET: locationIds/locationId, from, to. PUT: locationId, date, slots. DELETE: parámetros locationId y date. |
| GET, POST, DELETE | `/api/shifts` | GET: locationId, personId, date, from, to. POST: crear. DELETE: cuerpo JSON con id. |
| PUT | `/api/shifts/{id}` | Actualizar parcialmente un turno. |
| GET, DELETE | `/api/schedule-draft` | Leer el borrador compartido; includeChanges=true añade descripciones seguras. DELETE descarta todo el borrador. |
| POST | `/api/schedule-draft/publish` | Publicar todos los cambios pendientes de forma atómica. |
| GET, PUT | `/api/person-preferences` | GET: personIds/personId, from, to. PUT: personId, date, preference; un valor vacío elimina la preferencia. |
| GET, POST | `/api/timeoff/requests` | GET: status (requested por defecto; archived incluye approved/rejected). POST: personId, date, typeId; el horario procede de la plantilla. |
| PUT | `/api/timeoff/requests/{id}` | Actualizar nota/fecha o action: approve/reject. La plantilla y el horario no se pueden cambiar. |
| GET | `/api/timeoff/allowances` | Leer los saldos de permisos visibles. |
| GET, POST | `/api/timeoff/grants` | GET requiere personId. POST: personId, typeId, hours, note opcional. |
| DELETE | `/api/timeoff/grants/{id}` | Anular una asignación; el registro se conserva hasta eliminar la persona. |
| GET | `/api/overview` | Resumen con fechas start/end opcionales. |
| GET, PUT | `/api/workspace/ai-settings` | Leer reglas de IA; PUT sustituye rules o realiza la acción de regla admitida. |
| PATCH | `/api/workspace/rules/reset-interpretation` | Restablecer la interpretación con ruleId. |

Los campos de respuesta varían: persons, locations, shifts, schedules, preferences (con quotas), data (plantillas y solicitudes de permisos), grants (con summary) o allowances. No son arrays sin envoltorio. Las respuestas de escritura también varían según el endpoint.

Solo POST /api/shifts, DELETE /api/shifts, PUT /api/location-day-schedules, PUT /api/person-preferences y POST /api/timeoff/requests aceptan un { items: [...] }.

Los resultados por lote conservan el orden e incluyen successCount, failureCount, mutationCount y results. Un lote aceptado devuelve HTTP 200 aunque fallen algunos o todos sus elementos. Compruebe ok y status de cada resultado; HTTP 200 por sí solo no indica éxito.

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.

Los cambios en personas, ubicaciones o plantillas invalidan las interpretaciones de reglas IA. Eliminar personas o ubicaciones elimina datos de planificación dependientes. Los cambios de plantilla pueden requerir opciones de propagación; previsualice su impacto. Use un espacio de prueba para explorar las escrituras.

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