Concepts

Slot Computation

Slot Computation

When your agent calls GET /v1/humans/:id/slots, Slotflow runs a multi-step algorithm to compute exactly which time slots are available. Understanding this helps you set up schedules that produce the slots you expect.

The algorithm

For each day in the requested date range:

1. Check all-day block overrides → skip entire day if matched
2. Generate base schedule slots → from working_days + work_start/work_end
3. Apply time-specific blocks → remove overlapping slots
4. Apply open overrides → add extra slots outside base schedule
5. Deduplicate → remove slots that appear in both base and open windows
6. Filter existing bookings → remove slots occupied by confirmed bookings
7. Return remaining available slots (sorted by start time, in UTC)

Step by step example

Let’s trace through a real computation. Sarah has this setup:

Base schedule:

  • Working days: Monday-Friday (1-5)
  • Hours: 9:00 AM - 5:00 PM Eastern
  • Durations: 30 minutes

Overrides:

  • Block: Tuesday 2-3pm (weekly team standup)
  • Open: Saturday 10am-2pm (weekly overtime)

Existing bookings:

  • Monday 10:00-10:30 AM (confirmed)

An agent queries: GET /slots?date_from=2026-03-16&date_to=2026-03-21&duration=30

Monday (2026-03-16)

  1. No all-day block → proceed
  2. Monday is a working day → generate slots: 9:00, 9:30, 10:00, 10:30, … 16:30 (16 slots)
  3. No time-specific blocks for Monday → all 16 remain
  4. No open overrides for Monday → still 16
  5. Booking at 10:00-10:30 → remove that slot → 15 slots

Tuesday (2026-03-17)

  1. No all-day block → proceed
  2. Tuesday is a working day → generate slots: 9:00, 9:30, … 16:30 (16 slots)
  3. Block override: 2-3pm → remove 14:00, 14:30 slots → 14 slots
  4. No open overrides → still 14

Saturday (2026-03-21)

  1. No all-day block → proceed
  2. Saturday is NOT a working day → no base slots generated (0 slots)
  3. No time blocks to apply → still 0
  4. Open override: 10am-2pm → generate slots: 10:00, 10:30, 11:00, 11:30, 12:00, 12:30, 13:00, 13:30 → 8 slots

Sunday (not in range)

Not queried — date_to is March 21 (Saturday).

Final result

The API returns all available slots across the week, sorted by starts_at in UTC.

Time zones

All computation happens in the human’s local timezone. The slot engine:

  1. Receives date_from and date_to as dates (no time component)
  2. Interprets them in the human’s timezone
  3. Generates slots in the human’s local time
  4. Converts to UTC for the response

Example: Sarah is in America/New_York (UTC-5 in winter, UTC-4 in summer). Her 9:00 AM local time:

  • During EST (winter): returned as 14:00:00.000Z
  • During EDT (summer): returned as 13:00:00.000Z

Slotflow handles DST transitions automatically. Your agent doesn’t need to worry about it.

The timezone field in the response tells your agent which timezone the human is in, so it can convert UTC slots to the human’s local time for display purposes.

Edge cases

No availability rules

If a human has no availability rules configured, the slot engine returns an empty array unless there are open overrides that provide availability.

All-day block on a day with open overrides

All-day blocks take precedence. If Monday has both an all-day block and an open override, the entire day is skipped — no slots are generated.

Overlapping open and base schedule

If an open override window (e.g., 8am-12pm) overlaps with the base schedule (e.g., 9am-5pm), the slot engine deduplicates. You won’t get duplicate slots for the 9am-12pm overlap period.

Duration validation

The duration parameter must match one of the human’s meeting_durations. If the human allows [30, 60] and you request duration=45, you’ll get a 422 INVALID_DURATION error.

Empty date range

If no slots exist in the requested range (all days blocked, no base schedule, no open overrides), the API returns:

1{
2  "human_id": "...",
3  "duration": 30,
4  "timezone": "America/New_York",
5  "slots": [],
6  "total": 0
7}

This is not an error — it means the human is fully booked or unavailable in that period.

Performance considerations

  • The slot engine loads all overrides for a human in a single query (typically 10-50 overrides)
  • Computation is done in memory — no complex database queries per slot
  • Existing bookings are fetched for the requested date range only, not all bookings
  • For best performance, keep date ranges reasonable (1-2 weeks). Querying a full year would work but returns a large response