n8n-nodes-floyd

n8n community node for Floyd — atomic booking holds for AI agent workflows.

Problem: Voice agents and booking workflows can double-book when two requests race for the same slot. Calendar APIs don't prevent this.

Solution: Create a short-lived hold that blocks the slot while your agent confirms with the user. Only one workflow can win; everyone else gets an explicit conflict.

Installation

npm install n8n-nodes-floyd

Or in n8n: Settings → Community Nodes → Install → n8n-nodes-floyd

Quickstart

1. Get your API key: console.floyd.run → Organization → API Keys
2. Get a resource ID: Console → Resources → Create → Copy ID
3. Time format: ISO 8601 with timezone (e.g., 2026-01-12T14:00:00Z)
4. Add Floyd node: In n8n, search for "Floyd" and select an action
5. Three operations: Create Hold → Confirm Booking → Cancel Booking

The Floyd Node

The Floyd node provides three operations for atomic booking workflows:

Operation: Create Hold

Reserve a time slot with a TTL. The hold expires automatically if not confirmed.

Inputs

Field	Type	Required	Description
resourceId	string	Yes	The resource to book
startAt	datetime	Yes	Slot start time (ISO 8601)
endAt	datetime	Yes	Slot end time (ISO 8601)
ttlSeconds	number	No	Hold expiration in seconds (default: 300)
idempotencyKey	string	No	For retry-safe workflows
metadata	JSON	No	Arbitrary payload (customer info, etc.)

Options

Option	Default	Description
Return conflicts as output	ON	If ON, 409 conflicts flow as output (branchable). If OFF, node fails on conflict.

Outputs

Success:

{
  "bookingId": "bk_abc123",
  "status": "pending",
  "expiresAt": "2026-01-11T10:05:00Z",
  "requestId": "req_xyz789"
}

Conflict (when another hold/booking exists):

{
  "outcome": "conflict_overlap",
  "message": "Booking overlaps with existing pending or confirmed booking",
  "requestId": "req_xyz789"
}

---

Operation: Confirm Booking

Finalize a pending hold to convert it to a confirmed booking. Clears the expiration timer.

Inputs

Field	Type	Required	Description
bookingId	string	Yes	The booking ID from Floyd Create Hold

Outputs

Success:

{
  "bookingId": "bk_abc123",
  "status": "confirmed",
  "resourceId": "res_xyz",
  "startAt": "2026-01-13T10:00:00Z",
  "endAt": "2026-01-13T11:00:00Z",
  "confirmedAt": "2026-01-12T16:00:00Z",
  "requestId": "req_xyz789"
}

Errors:

• 404: Booking not found
• 409: Hold expired or already confirmed

---

Operation: Cancel Booking

Cancel a pending hold or confirmed booking. Releases the time slot and makes it available.

Inputs

Field	Type	Required	Description
bookingId	string	Yes	The booking ID to cancel

Outputs

Success:

{
  "bookingId": "bk_abc123",
  "status": "cancelled",
  "resourceId": "res_xyz",
  "startAt": "2026-01-13T10:00:00Z",
  "endAt": "2026-01-13T11:00:00Z",
  "cancelledAt": "2026-01-12T16:00:00Z",
  "requestId": "req_xyz789"
}

Errors:

• 404: Booking not found
• 409: Already cancelled or cannot cancel

Usage Examples

Voice Agent Booking Flow

Complete workflow with user confirmation:

┌────────────────────────┐
│ Webhook (Vapi/Retell)  │
└────────────┬───────────┘
             │  User: "Book me at 2pm"
             ▼
┌────────────────────────┐
│ Floyd: Create Hold     │
└────────────┬───────────┘
             │  Reserve slot (TTL: 5 min)
             ▼
┌────────────────────────┐
│ IF: conflict?          │
└────────────┬──────┬────┘
             │      │
             No     Yes
             │      │                ┌────────────────────────┐
             │      └──────────────▶ │ Respond: "Try 3pm?"    │
             │                       └────────────────────────┘
             ▼
┌────────────────────────┐
│ Ask user to confirm    │
└────────────┬──────┬────┘
             │      │
             Yes    No
             │      │                ┌────────────────────────┐
             │      └──────────────▶ │ Floyd: Cancel Booking  │
             │                       └────────────┬───────────┘
             │                                    │
             │                                    ▼
             │                       ┌────────────────────────┐
             │                       │ Respond: "Cancelled"   │
             │                       └────────────────────────┘
             ▼
┌────────────────────────┐
│ Floyd: Confirm Booking │
└────────────┬───────────┘
             │
             ▼
┌────────────────────────┐
│ Respond: "Confirmed!"  │
└────────────────────────┘

Simple Confirmation Flow

1. Floyd: Create Hold → Get bookingId
2. User confirms → Floyd: Confirm Booking with bookingId
3. User cancels → Floyd: Cancel Booking with bookingId

Hold Expiration (No Action)

If you don't confirm or cancel within ttlSeconds, the hold expires automatically:

Floyd: Create Hold (ttlSeconds: 300)
    │
    └─ 5 minutes pass...
    └─ Hold expires (no action needed)

Why holds instead of check-then-book?

The Problem with Check-Then-Book

The typical pattern:

1. Check availability
2. Ask user to confirm
3. Book the slot

The problem: Between step 1 and step 3, another request can book the same slot. You get double-bookings.

The Floyd Solution

Three-phase lifecycle:

1. Create Hold (atomic, blocks the slot) → status: "pending"
2. Ask user to confirm (slot is protected for ttlSeconds)
3. Confirm (finalize) → status: "confirmed" OR Cancel (release) → status: "cancelled"

Benefits:

• ✅ Only one workflow can hold a slot
• ✅ Conflicts are explicit (409 responses)
• ✅ Automatic cleanup (holds expire after TTL)
• ✅ Retry-safe (idempotency keys)
• ✅ Works with voice agents, forms, multi-step workflows

Credentials

1. Sign up at console.floyd.run
2. Create an organization and API key
3. In n8n: Credentials → New → Floyd API
4. Paste your API key
5. (Optional) Toggle "Show Advanced Options" to change the Base URL (for staging/self-hosted)

Links

• Floyd Documentation
• Voice Agent Booking Guide
• GitHub Issues

Troubleshooting

Error	Node	Cause	Fix
409 Conflict (overlap)	Create Hold	Slot already held/booked	Branch and offer alternative
409 Conflict (hold expired)	Confirm Booking	Hold TTL expired	Create new hold
409 Conflict (already confirmed)	Confirm Booking	Booking already finalized	Check booking status
409 Conflict (already cancelled)	Cancel Booking	Booking already cancelled	No action needed
404 Not Found	Confirm/Cancel	Invalid booking ID	Verify bookingId from Create Hold
422 Validation	Create Hold	Bad date format or endAt <= startAt	Check ISO 8601 format
401 Unauthorized	All	API key missing or wrong	Check credentials

Need help? Include the requestId from the output when contacting support.

License

MIT