> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.slotflow.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.slotflow.dev/_mcp/server.

# Slot Computation

> How Slotflow computes available time slots from availability rules, overrides, and existing bookings.

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:

```json
{
  "human_id": "...",
  "duration": 30,
  "timezone": "America/New_York",
  "slots": [],
  "total": 0
}
```

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