> 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.

# Node.js SDK

> Official TypeScript/Node.js SDK for the Slotflow API.

The official Slotflow SDK for Node.js and TypeScript. Fully typed, with automatic retries and error handling.

## Installation

```bash
npm install slotflow
```

## Quick example

```typescript
import { SlotflowClient } from "slotflow";

const client = new SlotflowClient({
  token: "sk_live_your_api_key",
});

// Find available slots
const { slots } = await client.slots.getAvailableSlots({
  humanId: "HUMAN_ID",
  date_from: "2026-03-15",
  date_to: "2026-03-20",
  duration: 30,
});

// Book the first slot
const booking = await client.bookings.createBooking({
  human_id: "HUMAN_ID",
  starts_at: slots[0].starts_at,
  duration: 30,
  attendee_name: "Alex Rivera",
  attendee_email: "alex@startup.io",
  metadata: {
    lead_id: "lead_8294",
    source: "ai_sdr",
  },
});
```

## Resources

All API resources are available as typed methods on the client:

| Resource                   | Methods                                                |
| -------------------------- | ------------------------------------------------------ |
| `client.humans`            | `createHuman`, `getHuman`, `listHumans`, `deleteHuman` |
| `client.availability`      | `setAvailability`                                      |
| `client.scheduleOverrides` | `createOverride`, `listOverrides`, `deleteOverride`    |
| `client.slots`             | `getAvailableSlots`                                    |
| `client.bookings`          | `createBooking`, `listBookings`, `cancelBooking`       |
| `client.webhooks`          | `createWebhook`, `listWebhooks`, `deleteWebhook`       |

## Error handling

The SDK throws typed errors you can catch and handle:

```typescript
import { SlotflowClient, Slotflow } from "slotflow";

try {
  await client.bookings.createBooking({ /* ... */ });
} catch (error) {
  if (error instanceof Slotflow.ConflictError) {
    // 409 — slot was just booked by someone else
    // Re-query slots and try the next one
  }
  if (error instanceof Slotflow.PaymentRequiredError) {
    // 402 — booking limit reached
  }
  if (error instanceof Slotflow.NotFoundError) {
    // 404 — human not found
  }
  if (error instanceof Slotflow.UnprocessableEntityError) {
    // 422 — validation error (outside working hours, invalid duration, etc.)
  }
}
```

## Configuration

```typescript
const client = new SlotflowClient({
  token: "sk_live_your_api_key",

  // Override the default timeout (seconds)
  timeoutInSeconds: 30,

  // Override the default retry count
  maxRetries: 3,

  // Custom fetch (e.g. for edge runtimes)
  fetch: myCustomFetch,
});
```

You can also override settings per request:

```typescript
await client.bookings.listBookings({}, {
  timeoutInSeconds: 10,
  maxRetries: 0,
});
```

## Requirements

* Node.js 18+
* Get your API key from the [Slotflow Dashboard](https://app.slotflow.dev)

## Links

* [npm package](https://www.npmjs.com/package/slotflow)
* [GitHub repository](https://github.com/nestorknf/slotflow-node)
* [API Reference](/api-reference)