LLMs & AI Agents

Slotflow is built from the ground up for AI agents. This page explains how to give your agent the context it needs to use the Slotflow API autonomously.

Machine-readable documentation

Slotflow provides two files specifically designed for AI agent consumption:

When to use which

• llms.txt — include in your agent’s system prompt when it needs to know what Slotflow is and what endpoints exist. Good for routing decisions (“should I use Slotflow for this?”).
• llms-full.txt — include when your agent needs to actually make API calls. Contains all the detail needed to construct requests, handle responses, and deal with errors.

System prompt example

Here’s how to give an AI agent context about Slotflow in its system prompt:

You are an AI sales development representative. You qualify inbound leads
and book demo meetings with the sales team.
When a lead is qualified and ready for a demo, use the Slotflow API to
schedule the meeting. Here is the API reference:
---
{contents of llms-full.txt}
---
Your Slotflow API key is available as the SLOTFLOW_API_KEY environment variable.
The sales team human IDs:
- Sarah Chen (Enterprise AE): hu_sarah_id
- Marcus Johnson (Mid-market AE): hu_marcus_id
Workflow:
1. Qualify the lead through conversation
2. When ready to book, call GET /v1/humans/:id/slots to find available times
3. Present 2-3 options to the lead
4. Once the lead picks a time, call POST /v1/bookings
5. Include lead_id and conversation_id in the booking metadata
6. If you get a 409 SLOT_UNAVAILABLE, re-query slots and try the next available time

Agent-friendly design decisions

Slotflow makes several design choices specifically for AI agent consumption:

Fixed time slots

The GET /slots endpoint returns discrete, bookable time slots — not raw calendar events or availability ranges. An agent can pick any slot from the array and book it directly. No ambiguity, no computation needed.

Deterministic responses

The same query to GET /slots always returns the same results (given the same schedule state). Agents can reason about availability without worrying about non-deterministic behavior.

Metadata passthrough

Every booking accepts an arbitrary metadata JSON object. Agents use this to carry workflow context:

1
{
2
  "lead_id": "lead_8294",
3
  "conversation_id": "conv_1847",
4
  "source": "ai_sdr",
5
  "qualified_at": "2026-03-10T13:45:00Z"
6
}

This metadata flows through to webhook payloads, so downstream systems receive the agent’s context without additional lookups.

Machine-readable errors

Every error has a stable code field:

1
{ "error": { "code": "SLOT_UNAVAILABLE", "message": "...", "status": 409 } }

Agents should switch on error.code, not parse error.message. Codes are stable; messages may change.

UTC timestamps

All times in API responses are ISO 8601 UTC. No timezone ambiguity. The timezone field in slot responses is purely informational for human-facing display.

Tool definition for function-calling agents

If your agent framework uses function/tool definitions (OpenAI function calling, Claude tool use, etc.), here’s the core Slotflow tool set:

1
[
2
  {
3
    "name": "slotflow_get_slots",
4
    "description": "Find available booking slots for a team member. Returns time slots in UTC.",
5
    "parameters": {
6
      "human_id": "UUID of the team member",
7
      "date_from": "Start date (YYYY-MM-DD)",
8
      "date_to": "End date (YYYY-MM-DD)",
9
      "duration": "Meeting duration in minutes (must match allowed durations)"
10
    }
11
  },
12
  {
13
    "name": "slotflow_create_booking",
14
    "description": "Book a specific time slot. Always call get_slots first to find valid times.",
15
    "parameters": {
16
      "human_id": "UUID of the team member",
17
      "starts_at": "Slot start time in UTC (from get_slots response)",
18
      "duration": "Meeting duration in minutes",
19
      "attendee_name": "Name of the person being booked",
20
      "attendee_email": "Email of the attendee (optional)",
21
      "metadata": "JSON object with workflow context (lead_id, ticket_id, etc.)"
22
    }
23
  },
24
  {
25
    "name": "slotflow_cancel_booking",
26
    "description": "Cancel an existing booking. Frees the time slot for other bookings.",
27
    "parameters": {
28
      "booking_id": "UUID of the booking to cancel"
29
    }
30
  }
31
]

Tips for AI agent developers

1. Always query slots before booking — don’t let the agent guess at times. The slots endpoint returns exactly what’s available.

2. Handle 409 errors — when multiple agents or users book simultaneously, slot conflicts happen. Build retry logic.

3. Use metadata — it’s the glue between your agent’s conversation and the booking lifecycle. Include everything your webhook handler needs.

4. Keep llms-full.txt in context — include it in the agent’s system prompt so it can construct correct API calls without hallucinating endpoints or parameters.

5. Present times in the user’s timezone — slots come back in UTC, but your end users think in local time. Convert using the timezone field from the slots response.