Skedulo Optimize API
The Optimize API from Skedulo — 2 operation(s) for optimize.
OpenAPI Specification
openapi: 3.0.0
info:
title: Authentication Admin Optimize API
description: Skedulo Authentication API
version: 1.0.0
servers:
- url: https://api.skedulo.com/auth
- url: https://api.uk.skedulo.com/auth
- url: https://api.ca.skedulo.com/auth
- url: https://api.au.skedulo.com/auth
tags:
- name: Optimize
paths:
/optimize/suggest:
post:
operationId: suggest
summary: Suggest times for a single job
description: 'Query the `/optimize/suggest` endpoint to find the best time to schedule a single job given a set of resources within a specific time range.
For example, if a job must be done on Thursday before noon you can specify the time window of 8AM to 12PM on Thursday and the resources that are available to find the best time to schedule the job that morning.
'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SuggestBodyResourceIds'
- $ref: '#/components/schemas/SuggestBodyResources'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuggestResponse'
tags:
- Optimize
/optimize/resource_suggestions:
post:
operationId: /optimize/resource_suggestions
summary: Suggest resources for a given job
description: 'Find the best resources within a given time range, for a given job and resource availabilities.
This query provides the amount of time each resource has available during the time period to complete the task.
* Resource availability is determined by working hours, holidays, existing jobs, shifts, and activities.
* You can provide availability directly (via `resources`) or by referencing existing resources (via `resourceIds`).
* Capacity fields (`currentCapacityInSeconds` and `newCapacityInSeconds`) show how much time a resource has available before and after scheduling the job.
**Availability Preferences**
You can optionally enable Availability Preferences using the `useAvailabilityPreferences` flag.
When `useAvailabilityPreferences` is set to `true`, Planr derives availability preferences for the job from enabled Jobs Record Filters and applies them when evaluating resource availability. This allows you to prioritise resources whose availability preferences match the job’s attributes.
Behaviour when `useAvailabilityPreferences` is enabled:
* Preferences are derived server-side from Jobs Record Filters associated with the given `jobId`.
* Only filters that apply to availability preferences are considered.
* If no relevant preferences are found for the job, the result is equivalent to calling the endpoint with `useAvailabilityPreferences` set to `false`.
* When `useAvailabilityPreferences` is omitted or `false`, resource suggestions do not consider availability preferences.
Unlike `/grid/schedule`, which accepts client-supplied `availabilityFilterValues`,
this endpoint derives availability preferences automatically from Jobs Record Filters
associated with the given `jobId`. The caller does not supply preference values directly;
Planr evaluates the job against all relevant filters to determine which preferences apply.
**Behaviour with `resources` availability window input**
When using the resources map variant (where availability windows are supplied directly),
Planr does not re-query the Availability engine, and useAvailabilityPreferences is ignored.
Preference evaluation is only applied for the `resourceIds` request shape.
'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ResourceSuggestionBodyResourceIds'
- $ref: '#/components/schemas/ResourceSuggestionBodyResources'
examples:
useAvailabilityPreferencesWithResourceIds:
summary: Use availability preferences (resourceIds)
value:
jobId: 0014cac9-4ba2-4944-b7ca-b4d2c40b1403
resourceIds:
- 0005ea18-61c1-49d9-9b50-d16a31a21c20
- 0005ade1-2a42-431f-a468-594ec4cb3261
scheduleStart: '2025-06-26T22:00:00.000Z'
scheduleEnd: '2025-06-27T04:00:00.000Z'
schedulingOptions:
jobTimeAsTimeConstraint: true
respectSchedule: true
regionId: 0005ea18-61c1-49d9-9b50-d16a31a21c20
useAvailabilityPreferences: true
useAvailabilityWithClientProvidedAvailabilityWindows:
summary: Use availability with client provided resource availability windows
value:
jobId: 0014cac9-4ba2-4944-b7ca-b4d2c40b1403
resources:
0005ea18-61c1-49d9-9b50-d16a31a21c20:
- start: '2025-06-26T22:00:00.000Z'
end: '2025-06-27T04:00:00.000Z'
0005ade1-2a42-431f-a468-594ec4cb3261:
- start: '2025-06-26T23:00:00.000Z'
end: '2025-06-27T03:00:00.000Z'
scheduleStart: '2025-06-26T22:00:00.000Z'
scheduleEnd: '2025-06-27T04:00:00.000Z'
schedulingOptions:
jobTimeAsTimeConstraint: true
respectSchedule: true
regionId: 0005ea18-61c1-49d9-9b50-d16a31a21c20
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSuggestionResponse'
examples:
preferencesEnabledExample:
summary: Availability preferences enabled (resource filtered out)
value:
result:
0005ce31-b45d-4b68-8c0a-eeed9ce82dfb:
resourceId: 0005ce31-b45d-4b68-8c0a-eeed9ce82dfb
allTagsUnmet: false
unmetTags: []
metTags: []
travelFromHome:
distanceFromHomeInMeters: 89995
durationFromHomeInMinutes: 68
feasible: true
score:
hard: 0
medium: 0
soft: -133
start: '2025-12-05T05:00:00.000Z'
durationInMinutes: 120
travelFromPreviousLocation:
previousLocationIsHome: true
distanceFromPreviousLocationInMeters: 89995
durationFromPreviousLocationInMinutes: 68
contextUtilizationInMinutes: 0
contextAvailabilityInMinutes: 1440
isAllocated: true
000592ab-a998-441c-a08d-598322f8d91d:
resourceId: 000592ab-a998-441c-a08d-598322f8d91d
allTagsUnmet: false
unmetTags: []
metTags: []
travelFromHome:
distanceFromHomeInMeters: 0
durationFromHomeInMinutes: 0
feasible: false
infeasibleReasons:
- type: resource_availability_preferences
rendered: 'Availability preference: Non Urgent Jobs'
onlyInfeasibleDueToAvailability: true
feasibleAvailability: false
contextUtilizationInMinutes: 30
contextAvailabilityInMinutes: 0
isAllocated: false
infeasibleDueToAvailabilityPreferences: true
availabilityPreferenceExplanation:
preferenceFiltered: true
matchingRecordFilterIds: []
mismatchedRecordFilterIds:
- 0042e422-06b2-4c74-8495-701a12d0545f
recordFiltersById:
0042e422-06b2-4c74-8495-701a12d0545f:
uid: 0042e422-06b2-4c74-8495-701a12d0545f
name: RF-0958
description: Non Urgent Jobs
expression: Urgency != 'Critical'
objectType: Jobs
preferencesMatchingExample:
summary: Availability preferences enabled (resource matched a preference)
value:
result:
0005ce31-b45d-4b68-8c0a-eeed9ce82dfb:
resourceId: 0005ce31-b45d-4b68-8c0a-eeed9ce82dfb
allTagsUnmet: false
unmetTags: []
metTags: []
travelFromHome:
distanceFromHomeInMeters: 89995
durationFromHomeInMinutes: 68
feasible: true
score:
hard: 0
medium: 0
soft: -133
start: '2025-12-05T05:00:00.000Z'
durationInMinutes: 120
travelFromPreviousLocation:
previousLocationIsHome: true
distanceFromPreviousLocationInMeters: 89995
durationFromPreviousLocationInMinutes: 68
contextUtilizationInMinutes: 0
contextAvailabilityInMinutes: 1440
isAllocated: true
000592ab-a998-441c-a08d-598322f8d91d:
resourceId: 000592ab-a998-441c-a08d-598322f8d91d
allTagsUnmet: false
unmetTags: []
metTags: []
travelFromHome:
distanceFromHomeInMeters: 0
durationFromHomeInMinutes: 0
feasible: false
infeasibleReasons: []
onlyInfeasibleDueToAvailability: true
feasibleAvailability: false
contextUtilizationInMinutes: 30
contextAvailabilityInMinutes: 0
isAllocated: false
infeasibleDueToAvailabilityPreferences: true
availabilityPreferenceExplanation:
preferenceFiltered: true
matchingRecordFilterIds:
- 0042e422-06b2-4c74-8495-701a12d0545f
mismatchedRecordFilterIds: []
recordFiltersById:
0042e422-06b2-4c74-8495-701a12d0545f:
uid: 0042e422-06b2-4c74-8495-701a12d0545f
name: RF-0958
description: Non Urgent Jobs
expression: Urgency != 'Critical'
objectType: Jobs
tags:
- Optimize
components:
schemas:
SchedulingOptions:
type: object
properties:
jobTimeAsTimeConstraint:
type: boolean
default: true
description: When a job has a time set, consider it to be a time constraint and never re-schedule to another time slot.
preferJobTimeOverTimeConstraint:
type: boolean
default: true
description: When a job with a JobTimeConstraint also has a time set, consider the job time as the authoritative constraint and ignore the JobTimeConstraint.
respectSchedule:
type: boolean
default: true
description: For a job that is allocated and in "Pending Dispatch" status, do not move the job to a different time.
ignoreTravelTimes:
type: boolean
default: false
description: Ignore all travel times between resources and jobs.
ignoreTravelTimeFirstJob:
type: boolean
default: false
description: Ignore travel time from a resource' home location to the first job.
ignoreTravelTimeLastJob:
type: boolean
default: false
description: Ignore travel time to the resource' home location from the last job.
assumeResourceCanTravelBeforeStart:
type: boolean
default: false
description: Ignore travel time to first job when deriving its arrival time however include the travel time when considering overall travel time reduction.
assumeResourceCanTravelAfterEnd:
type: boolean
default: false
description: Assume that the resource can travel after their end time to get to their end location however include the travel time when considering overall travel time reduction.
padding:
type: integer
default: 0
description: A fixed interval of time between consecutive jobs.
snapUnit:
type: integer
default: 0
minimum: 0
description: Divide the given time frame into parts described by this value and allocate all jobs to the nearest part.
RecordFilter:
type: object
additionalProperties: false
properties:
uid:
type: string
name:
type: string
description:
type: string
expression:
type: string
objectType:
type: string
SuggestBodyResourceIds:
type: object
properties:
suggestForNode:
type: string
description: ID of the job that you want the suggestion for.
resourceIds:
type: array
items:
type: string
scheduleStart:
$ref: '#/components/schemas/TimeStamp'
scheduleEnd:
$ref: '#/components/schemas/TimeStamp'
schedulingOptions:
$ref: '#/components/schemas/SchedulingOptions'
accountResourceScores:
type: array
description: An array of accounts and resources to blacklist
items:
$ref: '#/components/schemas/AccountResourceScores'
regionId:
type: string
description: 'Resource availability will be based on when resources are available in the region specified. Availability depends
on the primary region of the resource or whether the resource has Temporary or Secondary regions assigned.
'
required:
- suggestForNode
- resourceIds
- scheduleStart
- scheduleEnd
ResourceSuggestionResponse:
type: object
example: "{\n \"result\": {\n \"0005ea18-61c1-49d9-9b50-d16a31a21c20\": {\n \"resourceId\": \"0005ea18-61c1-49d9-9b50-d16a31a21c20\",\n \"jobId\": \"0014cac9-4ba2-4944-b7ca-b4d2c40b1403\",\n \"start\": \"2018-09-03T23:21:00.000Z\",\n \"duration\": 30,\n \"travelTime\": 17,\n \"currentCapacityInSeconds\": 86400,\n \"newCapacityInSeconds\": 83580\n }\n }\n}\n"
properties:
result:
type: object
additionalProperties:
type: object
properties:
resourceId:
type: string
description: UID of the resource.
jobId:
type: string
description: UID of the current job.
start:
type: string
format: date-time
description: Suggested start time of the job as an ISO8601 Date Time string.
duration:
type: integer
description: Duration (in minutes) of the current job.
travelTime:
type: integer
description: Travel time (in minutes) from the previous location (resource home or previous job) to the current job.
currentCapacityInSeconds:
type: integer
description: Available capacity for the resource based on currently scheduled jobs.
newCapacityInSeconds:
type: integer
description: Updated capacity for the resource once this job has been scheduled to the resource.
infeasibleDueToAvailabilityPreferences:
type: boolean
description: 'True when this resource is infeasible because its availability preferences do not match the job. Only set when `useAvailabilityPreferences` is true.
'
availabilityPreferenceExplanation:
type: object
nullable: true
description: 'Explanation of how availability preferences were applied to this resource. Present only when `useAvailabilityPreferences` is true and preferences were evaluated for this resource.
'
properties:
preferenceFiltered:
type: boolean
description: 'Indicates whether the resource was filtered by availability preferences.
'
matchingRecordFilterIds:
type: array
items:
type: string
description: IDs of record filters that matched this job for this resource.
mismatchedRecordFilterIds:
type: array
items:
type: string
description: IDs of record filters that did not match for this job/resource.
recordFiltersById:
type: object
description: 'Map of record filter IDs used in `matchingRecordFilterIds` and `mismatchedRecordFilterIds` to their definitions.
'
additionalProperties:
$ref: '#/components/schemas/RecordFilter'
ResourceSuggestionBodyResourceIds:
type: object
properties:
jobId:
type: string
description: UID of the job that you want the suggestion for.
resourceIds:
type: array
items:
type: string
scheduleStart:
$ref: '#/components/schemas/TimeStamp'
scheduleEnd:
$ref: '#/components/schemas/TimeStamp'
schedulingOptions:
$ref: '#/components/schemas/SchedulingOptions'
accountResourceScores:
type: array
description: An array of accounts and resources to blacklist
items:
$ref: '#/components/schemas/AccountResourceScores'
regionId:
type: string
description: 'Resource availability will be based on when resources are available in the region specified. Availability depends
on the primary region of the resource or whether the resource has Temporary or Secondary regions assigned.
'
useAvailabilityPreferences:
type: boolean
default: false
description: 'When true, derive and apply availability preferences for the given job using Jobs Availability Preferences.
Only resources whose availability matches the derived preferences are considered when suggesting resources.
If omitted or false, resource suggestions do not consider availability preferences.
If no relevant preferences are found for the job, this flag has no effect.
'
required:
- jobId
- resourceIds
- scheduleStart
- scheduleEnd
SuggestBodyResources:
type: object
properties:
suggestForNode:
type: string
description: ID of the job that you want the suggestion for.
resources:
description: A map of availability windows for each resource.
additionalProperties:
type: array
items:
type: object
properties:
start:
$ref: '#/components/schemas/TimeStamp'
end:
$ref: '#/components/schemas/TimeStamp'
scheduleStart:
$ref: '#/components/schemas/TimeStamp'
scheduleEnd:
$ref: '#/components/schemas/TimeStamp'
schedulingOptions:
$ref: '#/components/schemas/SchedulingOptions'
accountResourceScores:
type: array
description: An array of accounts and resources to blacklist
items:
$ref: '#/components/schemas/AccountResourceScores'
regionId:
type: string
description: 'Resource availability will be based on when resources are available in the region specified. Availability depends
on the primary region of the resource or whether the resource has Temporary or Secondary regions assigned.
'
required:
- suggestForNode
- resources
- scheduleStart
- scheduleEnd
ResourceSuggestionBodyResources:
type: object
properties:
jobId:
type: string
description: UID of the job that you want the suggestion for.
resources:
description: 'Use client-provided availability windows for each resource.
When using this form, Planr does not re-fetch availability from the Availability engine;
useAvailabilityPreferences is ignored.
'
additionalProperties:
type: array
items:
type: object
properties:
start:
$ref: '#/components/schemas/TimeStamp'
end:
$ref: '#/components/schemas/TimeStamp'
scheduleStart:
$ref: '#/components/schemas/TimeStamp'
scheduleEnd:
$ref: '#/components/schemas/TimeStamp'
schedulingOptions:
$ref: '#/components/schemas/SchedulingOptions'
accountResourceScores:
type: array
description: An array of accounts and resources to blacklist
items:
$ref: '#/components/schemas/AccountResourceScores'
regionId:
type: string
description: 'Resource availability will be based on when resources are available in the region specified. Availability depends
on the primary region of the resource or whether the resource has Temporary or Secondary regions assigned.
'
useAvailabilityPreferences:
type: boolean
default: false
description: 'Automatic availability preference evaluation is only available when using the `resourceIds` request
shape. When using the `resources` map variant, preference evaluation is always disabled.
'
required:
- jobId
- resources
- scheduleStart
- scheduleEnd
TimeStamp:
type: string
format: date-time
description: Can be either ISO8601 date time string or Unix timestamp number ( in milliseconds ). Always returned in ISO8601 format.
SuggestResponse:
type: object
example: "{\n \"result\": {\n \"routes\": {\n \"0005ea18-61c1-49d9-9b50-d16a31a21c20\": {\n \"resourceId\": \"0005ea18-61c1-49d9-9b50-d16a31a21c20\",\n \"route\": {\n \"jobId\": \"0014cac9-4ba2-4944-b7ca-b4d2c40b1403\",\n \"jobName\": \"JOB-0225\",\n \"start\": \"2018-09-03T23:21:00.000Z\",\n \"duration\": 40,\n \"travelTime\": 21,\n \"type\": \"job\"\n },\n \"gapList\": [\n {\n \"fromPrev\": {\n \"travelTime\": 21\n },\n \"interval\": {\n \"start\": \"2018-09-03T23:21:00.000Z\",\n \"end\": \"2018-09-04T00:01:00.000Z\"\n },\n \"toNext\": {\n \"travelTime\": 0\n }\n }\n ],\n \"isAllocated\": false\n }\n }\n }\n}\n"
properties:
result:
type: object
properties:
routes:
type: object
additionalProperties:
type: object
properties:
resourceId:
type: string
description: Id of the resource this suggestion is related to.
isAllocated:
type: boolean
description: Flag that signifies whether this resource has already been allocated to the job.
route:
type: object
properties:
duration:
type: integer
description: Duration ( in minutes ) of the current job.
jobId:
type: string
description: Id of the current job.
jobName:
type: string
description: Name of the current job ( Job.Name ).
start:
type: string
format: date-time
description: Suggested start time of the job as an ISO8601 Date Time string.
travelTime:
type: integer
description: Travel time ( in minutes ) from the previous location ( resource home or previous job ) to the current job.
type:
type: string
AccountResourceScores:
type: object
properties:
resourceId:
type: string
description: The resource id black listing or white listing jobs associated with the account id
accountId:
type: string
description: The account id associated with jobs black listing or white listing a resource
whitelist:
type: boolean
description: Is true if the resource and jobs assoicated with the account id are white listed
blacklist:
type: boolean
description: Is true if the resource and jobs associated with the account id are black listed
required:
- resourceId
- accountId
- whitelist
- blacklist
securitySchemes:
Authorization:
type: http
scheme: bearer
bearerFormat: JWT