API and Data Types Reference

API endpoints

All scheduler routes are mounted under /scheduler and require the scheduler workspace bundle plus authenticated access. My Day Run is the exception — available to any authenticated user.

Method	Path	Purpose
GET	`/scheduler/overview`	Full scheduler state: jobs, engineers, stats, insights
GET	`/scheduler/my-day-run`	Personal day-run for the authenticated user
GET	`/scheduler/day-run`	Engineer day-run plan with route suggestions
POST	`/scheduler/day-run/apply`	Commit suggested day-run stops
POST	`/scheduler/tasks`	Create a planner task
PATCH	`/scheduler/tasks/:id`	Update a planner task
POST	`/scheduler/bulk-update`	Bulk update up to 100 jobs
POST	`/scheduler/history/:id/undo`	Undo a scheduler change
POST	`/scheduler/bulk-create-inspections`	Batch create up to 50 inspections
POST	`/scheduler/deploy/preview`	Check deployment readiness for selected jobs
POST	`/scheduler/deploy/apply`	Deploy a batch and trigger engineer notifications
POST	`/scheduler/recurring-import/preview`	Preview a recurring CSV import
POST	`/scheduler/recurring-import/apply`	Commit a recurring import

Overview response shape

GET /scheduler/overview returns the complete scheduler state. All filter parameters are passed as query strings.

{
  jobs: SchedulerJob[],
  engineers: EngineerSummary[],
  filters: {
    start, end, engineerId, siteId, jobType, status, q,
    postcodeArea, region, equipment, ooh
  },
  stats: {
    totalJobs, scheduledJobs, unassignedJobs, overdueJobs,
    scheduledHours, conflictCount, unscheduledJobs,
    jobsWithWarnings, jobsWithBlockingWarnings, draftJobs,
    readyToDeployJobs, deployedTodayJobs, routeSuggestionCount,
    capacitySummary: {
      overloadedEngineers, availableEngineers,
      assignedHours, flaggedAssignments
    },
    warningBuckets: {
      blocked, flagged, unassigned, unscheduled,
      draft, ready, deployed, awaiting, acknowledged
    },
    actionCounts: {
      needsAssignment, needsScheduling, dueSoon,
      overloadedEngineers, readyToDeploy, draftJobs
    }
  },
  insights: {
    routeSuggestions: SchedulerRouteSuggestion[],
    recentChanges: SchedulerHistoryItem[],
    recentDeploymentBatches: DeploymentBatch[],
    selectionHints: { preferredAction, focusLabel }
  }
}

SchedulerJob type

The unified job object representing inspections, work orders, and planner tasks within the scheduler.

Field	Type	Description
`key`	string	Unique key: `"entityType:id"`
`id`	string	Entity ID
`entityType`	`"inspection"` \| `"work_order"` \| `"task"`	Source entity type
`jobType`	string	Specific type (e.g. `annual`, `remedial`, `survey`)
`title`	string	Display title
`subtitle`	string \| null	Secondary display text
`status`	string	Current status
`priority`	string \| null	`low`, `normal`, `high`, `urgent`
`scheduledDate`	string \| null	ISO datetime for exact scheduling
`targetMonth`	string \| null	`YYYY-MM` for month-level planning
`deploymentState`	`"draft"` \| `"deployed"`	Current deployment state
`deployedAt`	string \| null	ISO datetime of last deployment
`deployReady`	boolean	Whether the job can be deployed
`engineerAcknowledgedAt`	string \| null	ISO datetime when the engineer acknowledged the deployed work (via opening their day run). `null` if not yet acknowledged or not deployed.
`deployBlockedReasons`	string[]	Reasons blocking deployment
`estimatedDurationMinutes`	number	Estimated work duration
`scheduleWindowStart`	string \| null	Earliest acceptable date
`scheduleWindowEnd`	string \| null	Latest acceptable date
`scheduleFlexDays`	number \| null	Acceptable flex around scheduled date (0-120)
`siteId`	string \| null	Associated site
`siteName`	string \| null	Site display name
`systemId`	string \| null	Associated system
`systemName`	string \| null	System display name
`city`	string \| null	Site city
`postcode`	string \| null	Site postcode
`postcodeArea`	string \| null	Extracted area code (e.g. `SW` from `SW1A 1AA`)
`latitude`	string \| null	Site latitude
`longitude`	string \| null	Site longitude
`engineerIds`	string[]	Assigned engineer IDs
`engineerNames`	string[]	Assigned engineer display names
`requiredCompetencies`	string[]	Computed competency requirements
`crewSizeRequired`	number	Number of crew required (default 1)
`accessEquipment`	string[]	Normalised equipment values
`outOfHours`	boolean	Out-of-hours flag
`siteAccessNotes`	string \| null	Combined site access notes
`siteSchedulingRules`	object \| null	Site-level scheduling constraints
`validationWarnings`	SchedulerWarning[]	Current warnings
`detailHref`	string \| null	Link to the entity detail page

BulkUpdatePatch type

Sent to POST /scheduler/bulk-update. All fields are optional — only included fields are applied.

Field	Type	Constraints
`engineerId`	string \| null	Must be a valid org member with `canBeScheduled`
`scheduledDate`	string \| null	ISO datetime; mutually exclusive with `targetMonth`
`targetMonth`	string \| null	`YYYY-MM`; mutually exclusive with `scheduledDate`
`estimatedDurationMinutes`	number \| null	15-1440
`priority`	string	`low`, `normal`, `high`, `urgent`
`status`	string \| null	`pending`, `in_progress`, `completed`, `cancelled`
`scheduleWindowStart`	string \| null	ISO datetime
`scheduleWindowEnd`	string \| null	ISO datetime
`scheduleFlexDays`	number \| null	0-120
`crewSizeRequired`	number \| null	1-50
`accessEquipment`	string[] \| null	Validated against VALID_EQUIPMENT enum
`outOfHours`	boolean	—

EngineerSummary type

Field	Type	Description
`userId`	string	Engineer user ID
`role`	`"owner"` \| `"admin"` \| `"engineer"`	Organisation role
`canManageSchedule`	boolean	Whether the user can manage the scheduler
`canBeScheduled`	boolean	Whether the user can receive job assignments
`schedulerProfile`	object \| null	Availability and capacity settings
`user`	object	`{ id, name, email }`

Defaults and constants

Constant	Value	Used by
`DEFAULT_INSPECTION_FLEX_DAYS`	21	Inspection scheduling flex
`DEFAULT_WORK_FLEX_DAYS`	14	Work order scheduling flex
`DEFAULT_SHIFT_START_MINUTES`	480 (08:00)	Day-run and capacity calculations
`DEFAULT_SHIFT_END_MINUTES`	1020 (17:00)	Day-run and capacity calculations
`VALID_EQUIPMENT`	7 values	Equipment validation set
Max bulk update	100 jobs	Bulk update endpoint
Max batch inspections	50	Batch creation endpoint
Duration range	15-1440 minutes	All scheduling endpoints
Flex range	0-120 days	All scheduling endpoints
Crew range	1-50	All scheduling endpoints

How the scheduler connects to other workspaces

Workspace	Connection
Inspections	Created in the portal or via batch import, appear as schedulable jobs
Work orders	Created from accepted quotes or standalone, carry hold/resume lifecycle
Sites	Provide geographic data, scheduling rules, and access notes
Engineers	Form the assignment pool; availability and competencies tracked by capacity system
Deployment	Pushes scheduled work to the engineer's mobile day run
Finance	Follows after completed work; scheduler surfaces jobs needing invoicing
AI Assistant	Can be launched with current scheduler context for analysis