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://magpie.diy/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://magpie.diy/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" }
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). Times are in the account's time zone.

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)
timezone string IANA time zone that date and each slot's display are in, such as America/Los_Angeles. Defaults to the account's time zone.
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

Proposal Events

Sent to the webhooks of the person who owns the proposal.

  • proposal.sent - A proposal was sent
  • proposal.viewed - A recipient opened a proposal for the first time
  • proposal.accepted - A proposal was accepted
  • proposal.declined - A proposal was declined

Webinar Events

Sent to the webhooks of the person who created the webinar, while they are still a member of its team who can edit. data.webinar has uuid, title, starts_at and state; data.attendee has uuid, name, email, state, registered_at and joined_at. Nothing is sent for a test run.

  • webinar.registered - Someone registered on a webinar's registration page (data.attendee.state is registered, pending or waitlisted)
  • webinar.attended - An attendee joined the live webinar for the first time (usually sent within a minute)
  • webinar.ended - A webinar ended; data.registered and data.attended count its attendees

Webhook Payload Structure

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

Store

Orders, Products, stock, returns, customers and webhooks for the selected team's Store. Each route needs the matching Store permission; Store webhooks are for team admins. Amounts are whole numbers in the smallest unit of the Store's currency. Send an Idempotency-Key header with a refund or shipment so a retry is not applied twice.

GET /store-orders

List orders, with payment, fulfillment, tag and date filters

GET /store-orders/{uuid}

Read an order with its items, shipments, refunds, returns and history

POST /store-orders/{uuid}/fulfillments

Add a shipment

POST /store-orders/{uuid}/refunds

Refund all or part of an order and choose what returns to stock

POST /store-orders/{uuid}/notes

Add a note to the order's history

PUT /store-orders/{uuid}/tags

Replace the order's tags

GET /store-products

List Products with variant prices, SKUs and stock

PATCH /store-products/{uuid}/variants/{variantUuid}

Change a variant's price, compare-at price, SKU or stock on hand

POST /store-products/{uuid}/variants/{variantUuid}/adjustments

Add or remove stock with a reason

GET /store-inventory

List variants that track stock

GET /store-returns

List returns

GET /store-customers

List customers

GET /store-webhooks

List Store webhooks (team admins)

POST /store-webhooks

Add a Store webhook; the response shows its signing secret once

Store webhook events

  • store.order.paid - An order was paid
  • store.order.fulfilled - A shipment was added
  • store.order.refunded - A refund succeeded
  • store.order.canceled - An unpaid order was canceled
  • store.product.updated - A Product or its prices changed
  • store.stock.low - A variant reached its reorder point
  • store.return.requested - A customer asked to return items

Store webhooks use the same headers and signature as the webhooks above. X-Magpie-Id is the same on every retry. See Store API and webhooks.

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.