{ "openapi": "3.0.0", "info": { "title": "Magpie Meetings API", "version": "1.0.0", "description": "RESTful API for managing bookings, event types, availability, and webhooks", "contact": { "name": "Magpie Meetings", "url": "https://magpiemeetings.com" } }, "servers": [ { "url": "https://magpiemeetings.com/api/v1", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Token" } }, "schemas": { "Booking": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user_id": { "type": "integer" }, "attendee": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } } }, "sms_opt_in": { "type": "boolean" }, "sms_reminder_sent_at": { "type": "string", "format": "date-time", "nullable": true }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "notes": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["confirmed", "cancelled", "completed"] }, "host_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "zoom": { "type": "object", "properties": { "meeting_id": { "type": "string", "nullable": true }, "join_url": { "type": "string", "nullable": true }, "start_url": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true } } }, "google": { "type": "object", "properties": { "calendar_event_id": { "type": "string", "nullable": true }, "meet_link": { "type": "string", "nullable": true } } } } }, "EventType": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user_id": { "type": "integer" }, "name": { "type": "string" }, "duration_minutes": { "type": "integer" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Availability": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user_id": { "type": "integer" }, "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6 }, "start_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "end_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "User": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "slug": { "type": "string" }, "timezone": { "type": "string" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "secret_last4": { "type": "string", "nullable": true }, "secret": { "type": "string", "description": "Only returned when creating or rotating secret" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } }, "paths": { "/bookings": { "get": { "summary": "List bookings", "tags": ["Bookings"], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["confirmed", "cancelled", "completed"] } }, { "name": "start_time_gte", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "start_time_lte", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_archived", "in": "query", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of bookings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true } } } } } } } }, "post": { "summary": "Create a booking", "tags": ["Bookings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["attendee", "start_time", "duration_minutes"], "properties": { "attendee": { "type": "object", "required": ["name", "email"], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "timezone": { "type": "string" } } }, "start_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "event_type_uuid": { "type": "string", "format": "uuid" }, "notes": { "type": "string" }, "sms_opt_in": { "type": "boolean" }, "validate_only": { "type": "boolean" }, "send_notifications": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Booking created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } }, "409": { "description": "Booking conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bookings/{uuid}": { "get": { "summary": "Get a booking", "tags": ["Bookings"], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Booking details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a booking", "tags": ["Bookings"], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "attendee": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "timezone": { "type": "string" } } }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "notes": { "type": "string" }, "send_notifications": { "type": "boolean" }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Booking updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } } } }, "delete": { "summary": "Delete a booking", "tags": ["Bookings"], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Booking deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } }, "/bookings/{uuid}/cancel": { "post": { "summary": "Cancel a booking", "tags": ["Bookings"], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "send_notifications": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Booking cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } } } } }, "/bookings/{uuid}/confirm": { "post": { "summary": "Confirm a booking", "tags": ["Bookings"], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Booking confirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } } } } }, "/bookings/{uuid}/archive": { "post": { "summary": "Archive a booking", "tags": ["Bookings"], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Booking archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } } } } }, "/event-types": { "get": { "summary": "List event types", "tags": ["Event Types"], "parameters": [ { "name": "include_inactive", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of event types", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } } } } } } } } }, "post": { "summary": "Create an event type", "tags": ["Event Types"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "duration_minutes"], "properties": { "name": { "type": "string" }, "duration_minutes": { "type": "integer" }, "description": { "type": "string" }, "color": { "type": "string", "default": "#3B82F6" } } } } } }, "responses": { "201": { "description": "Event type created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EventType" } } } } } } } } }, "/event-types/{uuid}": { "patch": { "summary": "Update an event type", "tags": ["Event Types"], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "duration_minutes": { "type": "integer" }, "description": { "type": "string" }, "color": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Event type updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EventType" } } } } } } } }, "delete": { "summary": "Delete an event type", "tags": ["Event Types"], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event type deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } }, "/availability": { "get": { "summary": "List availability windows", "tags": ["Availability"], "responses": { "200": { "description": "List of availability windows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Availability" } } } } } } } } }, "post": { "summary": "Add availability window", "tags": ["Availability"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["day_of_week", "start_time", "end_time"], "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6 }, "start_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "end_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } } } } } }, "responses": { "201": { "description": "Availability window created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Availability" } } } } } } } } }, "/availability/slots": { "get": { "summary": "Get available time slots", "tags": ["Availability"], "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "duration_minutes", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of available time slots", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string", "format": "date-time" } } } } } } } } } }, "/availability/clear": { "post": { "summary": "Clear all availability", "tags": ["Availability"], "responses": { "200": { "description": "Availability cleared", "content": { "application/json": { "schema": { "type": "object", "properties": { "cleared": { "type": "boolean" } } } } } } } } }, "/availability/{uuid}": { "delete": { "summary": "Delete availability window", "tags": ["Availability"], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Availability window deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } }, "/users/me": { "get": { "summary": "Get current user", "tags": ["Users"], "responses": { "200": { "description": "Current user information", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } } } } } } }, "/webhooks": { "get": { "summary": "List webhooks", "tags": ["Webhooks"], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } } } }, "post": { "summary": "Create a webhook", "tags": ["Webhooks"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "url", "events"], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "booking.created", "booking.updated", "booking.rescheduled", "booking.cancelled", "booking.confirmed", "booking.deleted", "booking.archived", "event-type.created", "event-type.updated", "event-type.deleted" ] } }, "secret": { "type": "string" } } } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } } } } }, "/webhooks/{id}": { "patch": { "summary": "Update a webhook", "tags": ["Webhooks"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "rotate_secret": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } } } }, "delete": { "summary": "Delete a webhook", "tags": ["Webhooks"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } } } }