API Documentation

RESTful API for managing bookings, event types, availability, and webhooks

Introduction

The Magpie Meetings API provides programmatic access to your scheduling data. All API requests use JSON and follow REST conventions.

Base URL: https://magpiemeetings.com/api/v1

Authentication

All API requests require authentication using a Bearer token. Include your API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Generate API tokens from your account settings.

Quick Start

Here's a simple example to list your bookings:

curl -X GET https://magpiemeetings.com/api/v1/bookings \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json"

Bookings

Manage scheduled meetings and appointments.

GET /bookings

List all bookings

Query Parameters

Parameter Type Description
status string Filter by status: confirmed, cancelled, or completed
start_time_gte datetime Filter bookings starting on or after this time
start_time_lte datetime Filter bookings starting on or before this time
updated_since datetime Filter bookings updated since this time
include_archived boolean Include archived bookings (default: false)
limit integer Results per page (default: 50, max: 200)
offset integer Pagination offset (default: 0)
POST /bookings

Create a new booking

Request Body

{ "attendee": { "name": "Jane Smith", "email": "jane@example.com", "phone": "+1234567890", "timezone": "America/New_York" }, "start_time": "2026-03-15T14:00:00Z", "duration_minutes": 30, "event_type_uuid": "optional-event-type-uuid", "notes": "Optional meeting notes", "sms_opt_in": false, "send_notifications": true }
GET /bookings/{uuid}

Get a specific booking

PATCH /bookings/{uuid}

Update a booking

DELETE /bookings/{uuid}

Delete a booking

POST /bookings/{uuid}/cancel

Cancel a booking

POST /bookings/{uuid}/confirm

Confirm a booking as the host

POST /bookings/{uuid}/archive

Archive a booking

Event Types

Configure different types of meetings you offer.

GET /event-types

List all event types

Query Parameters

Parameter Type Description
include_inactive boolean Include inactive event types (default: false)
POST /event-types

Create a new event type

Request Body

{ "name": "30-Minute Consultation", "duration_minutes": 30, "description": "Brief consultation call", "color": "#3B82F6" }
PATCH /event-types/{uuid}

Update an event type

DELETE /event-types/{uuid}

Delete an event type

Availability

Manage your weekly availability schedule.

GET /availability

List all availability windows

POST /availability

Add an availability window

Request Body

{ "day_of_week": 1, "start_time": "09:00", "end_time": "17:00" }

Note: day_of_week is 0 (Sunday) through 6 (Saturday)

GET /availability/slots

Get available time slots for a specific date

Query Parameters

Parameter Type Description
date string Date in YYYY-MM-DD format (required)
duration_minutes integer Meeting duration in minutes (required)
DELETE /availability/{uuid}

Delete an availability window

POST /availability/clear

Clear all availability windows

Users

Get information about the authenticated user.

GET /users/me

Get current user information

Webhooks

Configure webhooks to receive real-time notifications about events.

GET /webhooks

List all webhooks

POST /webhooks

Create a new webhook

Request Body

{ "name": "Production Webhook", "url": "https://example.com/webhook", "events": [ "booking.created", "booking.cancelled", "event-type.created" ], "secret": "optional-custom-secret" }
PATCH /webhooks/{id}

Update a webhook

Request Body

{ "name": "Updated name", "url": "https://example.com/new-webhook", "events": ["booking.created"], "is_active": true, "rotate_secret": true }
DELETE /webhooks/{id}

Delete a webhook

Webhook Signature Verification

All webhook requests include an X-Magpie-Signature header for verification:

X-Magpie-Signature: t=1234567890,v1=hash

Verify by computing HMAC-SHA256 of timestamp.body using your webhook secret.

Webhook Events

Available event types for webhook subscriptions:

Booking Events

  • booking.created - A new booking was created
  • booking.updated - A booking was updated
  • booking.rescheduled - A booking time was changed
  • booking.cancelled - A booking was cancelled
  • booking.confirmed - A booking was confirmed by the host
  • booking.deleted - A booking was deleted
  • booking.archived - A booking was archived

Event Type Events

  • event-type.created - A new event type was created
  • event-type.updated - An event type was updated
  • event-type.deleted - An event type was deleted

Webhook Payload Structure

{ "id": "evt_abc123def456", "type": "booking.created", "created_at": "2026-03-15T14:30:00Z", "data": { "booking": { ... } } }

OpenAPI Specification

Download the complete machine-readable API specification:

Download OpenAPI 3.0 Spec

Use this specification with tools like Postman, Swagger UI, or to generate client libraries.