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.
| |
|---|
| Who | Agents can call this |
| REST | POST /v1/schedule/find-time |
| MCP tool | schedule_findTime |
| Writes | no |
| Area | Scheduling 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.
| Field | Type | Required |
|---|
shop_id | string (uuid) | yes |
duration_minutes | integer | yes |
from | string (date-time) | no |
to | string (date-time) | no |
person_ids | array | no |
crew_id | string (uuid) | no |
together | boolean | no |
step_minutes | integer | no |
limit | integer | no |
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
| Field | Type | Always there |
|---|
time_zone | string | yes |
hours_source | string (one of shop, default) | yes |
buffer_minutes | integer | yes |
arrival_window_minutes | integer | no |
slots | array | yes |
slots[].starts_at | string (date-time) | yes |
slots[].ends_at | string (date-time) | yes |
slots[].arrive_by | string (date-time) | yes |
slots[].person_ids | array | yes |
slots[].local | string | yes |
slots[].tz | string | yes |
{
"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
| Code | Status | What to do |
|---|
invalid_input, invalid_token, rate_limited | | Can happen on any call. See errors. |