# API Reference

> LinkTime REST API — 12 authenticated endpoints + 1 public booking endpoint.
> Source: https://linktime.io/docs/developers/api
> Last updated: February 2026

## Getting Started

1. Upgrade to Pro or Business plan
2. Go to Settings → API Keys → Create API Key
3. Copy the key (shown once — cannot be retrieved later)
4. Test: `curl -H "Authorization: Bearer YOUR_KEY" https://linktime.io/api/v1/me`

API keys start with `lt_live_`. Each key is scoped to the user who created it.

## Authentication

All `/api/v1/*` endpoints require a Bearer token:

```
Authorization: Bearer lt_live_...
```

## Endpoints

### User

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/me` | Current user info (id, email, name, username, plan, effectivePlan) |

### Bookings

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/bookings` | List bookings. Params: `page`, `limit` (max 100), `status` (CONFIRMED\|CANCELLED\|all), `from`, `to` (ISO dates) |
| `GET` | `/api/v1/bookings/:id` | Booking detail with event type, contact, and email logs |
| `POST` | `/api/v1/bookings/:id/cancel` | Cancel a booking. Body: `{ "reason": "..." }`. Fires all side effects (calendar, CRM, email, webhooks). |

### Contacts

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/contacts` | List/search contacts. Params: `search`, `page`, `limit` |
| `POST` | `/api/v1/contacts` | Create a contact. Body: `{ "name", "email", "phone?", "company?", "notes?" }`. Fires `contact.created` webhook. |
| `GET` | `/api/v1/contacts/:id` | Contact detail with upcoming/past meetings |
| `PATCH` | `/api/v1/contacts/:id` | Update a contact (partial). Email uniqueness enforced. |
| `DELETE` | `/api/v1/contacts/:id` | Delete a contact |

### Event Types

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/event-types` | List active event types |
| `GET` | `/api/v1/event-types/:id` | Event type detail (includes scheduling config) |

### Availability

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/availability/:slug` | Available time slots. Params: `timezone` (required), `startDate`, `endDate` |

### Public Booking (No Auth Required)

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/bookings` | Create a booking. Body: `{ "eventTypeId", "inviteeName", "inviteeEmail", "inviteeTimezone", "startTime" }` |

## Response Format

### Single Resource

```json
{ "id": "...", "name": "...", "createdAt": "2026-02-14T10:00:00.000Z" }
```

### List with Pagination

```json
{
  "data": [...],
  "pagination": { "page": 1, "limit": 20, "total": 156, "totalPages": 8 }
}
```

### Error

```json
{ "error": "message", "details": { "field": "validation message" } }
```

## Rate Limits

- **API key endpoints:** 60 requests/minute per API key
- **Pre-auth protection:** 5 requests/minute per IP
- **Public booking:** 10 requests/minute per IP

429 responses include a `Retry-After` header.

## HTTP Status Codes

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 201 | Created (POST /contacts) |
| 400 | Bad request |
| 401 | Authentication failed |
| 404 | Not found or not owned by you |
| 409 | Conflict (duplicate email) |
| 429 | Rate limited |
| 500 | Server error |

## Webhook Events

Configure webhooks in your dashboard (not via API). See [Webhooks API](https://linktime.io/docs/developers/webhooks).

| Event | Description |
|-------|-------------|
| `booking.created` | A new booking has been confirmed |
| `booking.cancelled` | A booking has been cancelled |
| `booking.rescheduled` | A booking has been moved to a new time |
| `payment.received` | Payment completed for a paid booking |
| `contact.created` | A new contact was added |

## Related Documentation

- [Webhooks API](https://linktime.io/docs/developers/webhooks) — Full payload reference and signature verification
- [Embed Widget](https://linktime.io/docs/developers/embed) — Add booking to your website
- [Make.com Integration](https://linktime.io/docs/automation/make) — Connect to 1000+ apps
- [Quickstart Guide](https://linktime.io/docs/getting-started/quickstart) — Get started in 5 minutes