schedule.findTime

Find open times for a visit of a given length; each slot has starts_at in UTC plus local shop time and tz (for example local 2026-11-10 8:00 AM, tz America/Boise). Looks inside shop hours (or Monday to Friday 08:00 to 17:00 when none are set), skips worker time off and times outside a worker's own hours, and keeps the shop's travel buffer clear around booked visits. Give person_ids or a saved crew_id (or both) to check those workers (together: all of them free at once, the default; or any one of them). Leave it out to check every worker in the shop and get back who is free. A lead can check the crews they belong to or lead. Field workers can only check themselves. Nothing is booked; call visits.create with a slot.

WhoAgents can call this
RESTPOST /v1/schedule/find-time
MCP toolschedule_findTime
Writesno
AreaScheduling and visits

When to use it

Find open times for a visit of a given length; each slot has starts_at in UTC plus local shop time and tz (for example local 2026-11-10 8:00 AM, tz America/Boise). Looks inside shop hours (or Monday to Friday 08:00 to 17:00 when none are set), skips worker time off and times outside a worker's own hours, and keeps the shop's travel buffer clear around booked visits.

What to tell the owner

Tell them what you found in plain words. Don't read back raw fields.

Input

FieldTypeRequired
shop_idstring (uuid)yes
duration_minutesintegeryes
fromstring (date-time)no
tostring (date-time)no
person_idsarrayno
crew_idstring (uuid)no
togetherbooleanno
step_minutesintegerno
limitintegerno

Example

POST https://doingwork.work/v1/schedule/find-time
content-type: application/json
Idempotency-Key: 3f1c...

{
  "shop_id": "00000000-0000-4000-8000-000000000000",
  "duration_minutes": 1
}

Output

FieldTypeAlways there
time_zonestringyes
hours_sourcestring (one of shop, default)yes
buffer_minutesintegeryes
arrival_window_minutesintegerno
slotsarrayyes
slots[].starts_atstring (date-time)yes
slots[].ends_atstring (date-time)yes
slots[].arrive_bystring (date-time)yes
slots[].person_idsarrayyes
slots[].localstringyes
slots[].tzstringyes
{
  "time_zone": "...",
  "hours_source": "shop",
  "buffer_minutes": 1,
  "slots": [
    {
      "starts_at": "...",
      "ends_at": "...",
      "arrive_by": "...",
      "person_ids": [
        "00000000-0000-4000-8000-000000000000"
      ],
      "local": "...",
      "tz": "..."
    }
  ]
}

Errors

CodeStatusWhat to do
invalid_input, invalid_token, rate_limitedCan happen on any call. See errors.