Scheduling API

Endpoints for managing schedules, shifts, and templates.

Shift Templates

List Templates

GET/api/scheduling/templatesAuth: Session

Get all shift templates.

Response (200):

json

{
  "templates": [
    {
      "id": "uuid",
      "name": "Morning Shift",
      "startTime": "08:00",
      "endTime": "16:00",
      "durationMinutes": 480,
      "breakRules": [
        { "startOffset": 240, "duration": 60, "type": "lunch" }
      ],
      "daysOfWeek": [1, 2, 3, 4, 5],
      "color": "#3b82f6"
    }
  ]
}

Create Template

POST/api/scheduling/templatesAuth: Session

Create a new shift template.

Request Body:

json

{
  "name": "Morning Shift",
  "startTime": "08:00",
  "endTime": "16:00",
  "breakRules": [
    { "startOffset": 120, "duration": 15, "type": "break" },
    { "startOffset": 240, "duration": 60, "type": "lunch" }
  ],
  "daysOfWeek": [1, 2, 3, 4, 5],
  "color": "#3b82f6"
}

Parameter	Type	Required	Description
`name`	string	Required	Template name (1-100 chars)
`startTime`	string	Required	Start time (HH:MM)
`endTime`	string	Required	End time (HH:MM)
`breakRules`	array	Optional	Break definitions
`daysOfWeek`	array	Optional	Days (0=Sun, 6=Sat)
`color`	string	Optional	Hex color code

Update Template

PUT/api/scheduling/templates/:idAuth: Session

Update an existing template.

Delete Template

DELETE/api/scheduling/templates/:idAuth: Session

Delete a template.

Schedules

List Schedules

GET/api/scheduling/schedulesAuth: Session

Get schedules with optional filters.

Query Parameters:

Parameter	Type	Required	Description
`status`	string	Optional	Filter: "draft", "published", "locked"
`startDate`	string	Optional	Filter by start date
`endDate`	string	Optional	Filter by end date

Response (200):

json

{
  "schedules": [
    {
      "id": "uuid",
      "name": "Week of Feb 1",
      "startDate": "2026-02-01",
      "endDate": "2026-02-07",
      "status": "draft",
      "shiftCount": 45,
      "employeeCount": 12
    }
  ]
}

Create Schedule

POST/api/scheduling/schedulesAuth: Session

Create a new schedule.

Request Body:

json

{
  "name": "Week of Feb 1",
  "startDate": "2026-02-01",
  "endDate": "2026-02-07"
}

Get Schedule Details

GET/api/scheduling/schedules/:idAuth: Session

Get schedule with all shifts.

Response (200):

json

{
  "schedule": {
    "id": "uuid",
    "name": "Week of Feb 1",
    "status": "draft",
    "startDate": "2026-02-01",
    "endDate": "2026-02-07"
  },
  "shifts": [
    {
      "shift": {
        "id": "uuid",
        "date": "2026-02-01",
        "startTime": "08:00",
        "endTime": "16:00"
      },
      "employee": {
        "id": "uuid",
        "firstName": "John",
        "lastName": "Doe"
      },
      "template": {
        "name": "Morning Shift",
        "color": "#3b82f6"
      }
    }
  ]
}

Update Schedule

PATCH/api/scheduling/schedules/:idAuth: Session

Update schedule (e.g., publish).

Request Body:

json

{
  "status": "published"
}

Delete Schedule

DELETE/api/scheduling/schedules/:idAuth: Session

Delete a schedule.

Shifts

List Shifts

GET/api/scheduling/shiftsAuth: Session

Get shifts with filters.

Query Parameters:

Parameter	Type	Required	Description
`scheduleId`	string	Optional	Filter by schedule
`employeeId`	string	Optional	Filter by employee
`date`	string	Optional	Filter by date

Create Shifts

POST/api/scheduling/shiftsAuth: Session

Create one or more shifts.

Request Body (Single Shift):

json

{
  "scheduleId": "uuid",
  "employeeId": "uuid",
  "templateId": "uuid",
  "date": "2026-02-01",
  "startTime": "08:00",
  "endTime": "16:00"
}

Request Body (Bulk):

json

{
  "shifts": [
    {
      "scheduleId": "uuid",
      "employeeId": "uuid",
      "date": "2026-02-01",
      "startTime": "08:00",
      "endTime": "16:00"
    }
  ]
}

Update Shift

PUT/api/scheduling/shifts/:idAuth: Session

Update a shift.

Delete Shift

DELETE/api/scheduling/shifts/:idAuth: Session

Delete a shift.

Auto-Generate Schedule

POST/api/scheduling/generateAuth: Session

Auto-generate an optimal schedule.

Request Body:

json

{
  "name": "Auto-Generated Week",
  "startDate": "2026-02-01",
  "endDate": "2026-02-07",
  "employeeIds": ["uuid1", "uuid2"],
  "templateIds": ["uuid1"],
  "options": {
    "coverageTarget": 10,
    "respectAvailability": true,
    "balanceHours": true
  }
}

Parameter	Type	Required	Description
`name`	string	Required	Schedule name
`startDate`	string	Required	Start date
`endDate`	string	Required	End date
`employeeIds`	array	Required	Employees to schedule
`templateIds`	array	Optional	Templates to use
`options`	object	Optional	Generation options

Response (201):

json

{
  "success": true,
  "schedule": {
    "id": "uuid",
    "name": "Auto-Generated Week",
    "shiftCount": 35
  }
}

Clone Schedule

Clone a Schedule

POST/api/scheduling/schedules/:id/cloneAuth: Session

Create a copy of a schedule with all shift assignments offset to a new date range. The cloned schedule is always created as a draft. Admin only.

Request Body:

Parameter	Type	Required	Description
`name`	string	Required	Name for the cloned schedule
`startDate`	string	Required	Start date (YYYY-MM-DD) for the new schedule

Response (200):

json

{
  "success": true,
  "message": "Schedule cloned with 35 shifts",
  "schedule": {
    "id": "uuid",
    "name": "Copy of Week 12",
    "startDate": "2026-03-22",
    "endDate": "2026-03-28",
    "status": "draft"
  },
  "stats": {
    "totalShifts": 35
  }
}

The end date is auto-calculated from the source schedule's duration. All shift times are preserved; only dates are offset.

Biddable Shifts (Pro+)

Shift bidding requires the Pro or Enterprise subscription tier.

List Biddable Shifts

GET/api/scheduling/biddable-shiftsAuth: Session

Get open shifts available for employee bidding.

Create Biddable Shift

POST/api/scheduling/biddable-shiftsAuth: Session

Create a new biddable shift.

Update Biddable Shift

PATCH/api/scheduling/biddable-shifts/:idAuth: Session

Update a biddable shift.

Delete Biddable Shift

DELETE/api/scheduling/biddable-shifts/:idAuth: Session

Remove a biddable shift.