API Documentation

Spots represent where work happens-think of them as locations, stations, or roles. Each spot defines which teams and skills are required to work there, plus special rules about rest requirements and employee continuity.

Spot structure

{
  "id": 5,
  "requiresRestAfterShiftHere": false,
  "singleEmployeePerWeekPreferred": false,
  "teams": [2, 3],
  "skills": [10, 12],
  "foreignInt": null
}

All fields except foreignInt are required.

Basic fields

  • id - Unique identifier for this spot
  • teams - Array of team IDs allowed to work here (empty array means any team)
  • skills - Array of skill IDs required to work here (empty array means no special skills needed)

The solver only assigns employees who belong to an allowed team (during the shift's time period) and possess all required skills.

Rest requirements

{
  "requiresRestAfterShiftHere": true
}

Set this to true for physically or mentally demanding spots where employees need recovery time. When enabled, the solver ensures employees get a day off after working shifts at this spot.

Use this for:

  • Night shifts
  • High-stress positions (emergency departments, intensive care)
  • Physically demanding roles

The solver treats this as a hard constraint or penalizes violations based on your settings.

Minute-based rest windows

In addition to full days off, you can require a specific number of minutes of rest after working in a spot:

{
  "id": 11,
  "requiresRestAfterShiftHere": false,
  "requiresRestOfMinutes": 720
}
  • requiresRestOfMinutes - Minimum number of minutes that must elapse between the end of any shift in this spot and the start of the employee’s next shift (in any spot).

This lets you model demanding environments that require, for example, 12 hours of rest before any further work. To activate this constraint, configure the restAfterShiftInRoomWithRequiredMinutes setting in your settings. When the setting weight is zero, requiresRestOfMinutes is ignored.

Employee continuity

{
  "singleEmployeePerWeekPreferred": true
}

Set this to true when you prefer the same employee to handle all shifts at this spot during a week. This creates consistency for roles where handoffs are costly or where building context matters.

Use this for:

  • Patient care continuity
  • Project-based work
  • Roles with significant setup/handoff overhead

This is a soft constraint-the solver tries to maintain continuity but will break it if necessary to satisfy higher-priority constraints.

Foreign key tracking

{
  "foreignInt": 42
}

Use foreignInt to track your system's identifier for this spot. The solver returns this value unchanged in the solution.

Examples

An emergency department spot requiring specific skills and rest after shifts:

{
  "id": 10,
  "requiresRestAfterShiftHere": true,
  "singleEmployeePerWeekPreferred": false,
  "teams": [1, 2],
  "skills": [5, 8],
  "foreignInt": 101
}

This spot requires employees from team 1 or 2, with both skills 5 and 8. After working here, employees must have time to recover.

A patient care role preferring continuity:

{
  "id": 15,
  "requiresRestAfterShiftHere": false,
  "singleEmployeePerWeekPreferred": true,
  "teams": [3],
  "skills": [12],
  "foreignInt": 202
}

This spot prefers the same employee throughout the week for consistent patient care.

A general-purpose spot with no special requirements:

{
  "id": 20,
  "requiresRestAfterShiftHere": false,
  "singleEmployeePerWeekPreferred": false,
  "teams": [],
  "skills": [],
  "foreignInt": null
}

Any qualified employee can work here, with no special rules.