{ "openapi": "3.1.0", "info": { "title": "Creavi Booking API", "version": "1.3.0", "description": "Site-owner-approved integrations over HTTPS. Managed connections have explicit permissions for services, availability, booking creation, owned-booking reads, and sensitive all-booking reads. GET /bookings defaults to today and supports bounded date-range paging for MCP and other clients. See booking-api.md for connection management, limits, privacy, and retry semantics." }, "servers": [ { "url": "https://your-site.example/wp-json/creavi-booking/v1" } ], "security": [ { "applicationPassword": [] } ], "paths": { "/connection": { "get": { "operationId": "testConnection", "summary": "Verify authentication and inspect effective API permissions", "responses": { "200": { "description": "Connection details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API is disabled, HTTPS is unavailable, the managed connection is expired/revoked, or the account has no Booking API permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The account exceeded its request limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services": { "get": { "operationId": "listServices", "summary": "List published, unprotected services", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Services", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "headers": { "X-WP-Total": { "schema": { "type": "integer" } }, "X-WP-TotalPages": { "schema": { "type": "integer" } } } }, "400": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services/{id}": { "get": { "operationId": "getService", "summary": "Get service fields and consent policy", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services/{id}/availability": { "get": { "operationId": "findAvailability", "summary": "Get available appointments on one service-local date", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Available appointments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "400": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bookings": { "get": { "operationId": "listBookings", "summary": "List today's bookings or an inclusive date range", "description": "Returns connection-owned bookings unless the credential has creavibc_api_read_all_bookings. Lists compact summaries; use /bookings/{id} for full details.", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Start appointment date. Defaults to the current date in the WordPress site timezone." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive end appointment date. Defaults to from; maximum range is 93 inclusive days." }, { "name": "service_id", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "Booking summaries and pagination.", "headers": { "X-WP-Total": { "schema": { "type": "integer" } }, "X-WP-TotalPages": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingList" } } } }, "400": { "description": "Invalid or excessive date range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API disabled, HTTPS unavailable, or booking-read permission missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createBooking", "summary": "Create a booking or replay an existing request", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{16,128}$" } } ], "requestBody": { "required": true, "description": "Maximum 64 KiB. Use a time returned by availability. Custom-field answers are strings keyed by field ID. Required customer fields depend on the service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBooking" } } } }, "responses": { "201": { "description": "Booking created; delivery problems do not undo the booking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } }, "headers": { "Location": { "schema": { "type": "string" } } } }, "200": { "description": "Original booking; replayed is true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bookings/{id}": { "get": { "operationId": "getBooking", "summary": "Get full details for a visible booking", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Inspect code and data.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Owned bookings are visible with creavibc_api_read_booking. Any booking is visible only with creavibc_api_read_all_bookings or administrator access." } } }, "components": { "securitySchemes": { "applicationPassword": { "type": "http", "scheme": "basic", "description": "Generated technical username and WordPress Application Password belonging to a restricted integration account. HTTPS required." } }, "schemas": { "Connection": { "type": "object", "additionalProperties": false, "required": [ "connected", "api_version", "username", "permissions", "authentication", "limits", "idempotency_retention_days" ], "properties": { "connected": { "type": "boolean", "const": true }, "api_version": { "type": "string", "const": "1" }, "username": { "type": "string" }, "connection_name": { "type": "string", "description": "Friendly name returned for plugin-managed connections only." }, "credential_expires_at": { "description": "ISO 8601 expiry for a plugin-managed connection, or null when it never expires.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "permissions": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "read_services", "read_availability", "create_booking", "read_booking", "read_all_bookings" ] } }, "authentication": { "type": "string", "const": "wordpress_application_password" }, "limits": { "type": "object", "additionalProperties": false, "required": [ "requests_per_minute", "writes_per_minute" ], "properties": { "requests_per_minute": { "type": "integer", "const": 120 }, "writes_per_minute": { "type": "integer", "const": 20 } } }, "idempotency_retention_days": { "type": "integer", "const": 7 } } }, "CreateBooking": { "type": "object", "additionalProperties": false, "required": [ "service_id", "starts_at", "customer" ], "properties": { "service_id": { "type": "integer", "minimum": 1 }, "starts_at": { "type": "string", "maxLength": 25, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:00(Z|[+-]\\d{2}:\\d{2})$" }, "customer": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 50 }, "timezone": { "type": "string", "maxLength": 100 } } }, "comment": { "type": "string", "maxLength": 5000 }, "custom_fields": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 5000 } }, "consent": { "type": "object", "additionalProperties": false, "required": [ "accepted", "policy_version" ], "properties": { "accepted": { "type": "boolean" }, "policy_version": { "type": "string", "minLength": 64, "maxLength": 64 } } } } }, "Service": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "duration_minutes": { "type": "integer" }, "timezone": { "type": "string" }, "booking_fields": { "type": "object", "properties": { "name": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "required": { "type": "boolean" }, "label": { "type": "string" } } }, "email": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "required": { "type": "boolean" }, "label": { "type": "string" } } }, "phone": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "required": { "type": "boolean" }, "label": { "type": "string" } } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "tel", "number", "date" ] }, "required": { "type": "boolean" } }, "required": [ "id", "label", "type", "required" ] } }, "consent": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "required": { "type": "boolean" }, "label": { "type": "string" }, "privacy_url": { "type": "string" }, "policy_version": { "type": "string", "minLength": 64, "maxLength": 64 } } } }, "required": [ "id", "name", "duration_minutes", "timezone", "booking_fields", "custom_fields", "consent" ] }, "Booking": { "type": "object", "properties": { "id": { "type": "integer" }, "service_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "confirmed" ] }, "starts_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "duration_minutes": { "type": "integer" }, "timezone": { "type": "string" }, "customer_timezone": { "type": "string" }, "location": { "type": "string" }, "replayed": { "type": "boolean" }, "meeting": { "type": "object", "properties": { "type": { "type": "string" }, "provider": { "type": "string" }, "address": { "type": "string" }, "phone": { "type": "string" }, "join_url": { "type": "string" } }, "additionalProperties": false }, "delivery_status": { "type": "string", "enum": [ "processing", "complete", "needs_attention", "unknown" ] }, "delivery": { "type": "object", "properties": { "email_admin": { "type": "string", "enum": [ "not_requested", "processing", "accepted", "success", "failed", "ready", "unknown" ] }, "email_customer": { "type": "string", "enum": [ "not_requested", "processing", "accepted", "success", "failed", "ready", "unknown" ] }, "google": { "type": "string", "enum": [ "not_requested", "processing", "accepted", "success", "failed", "ready", "unknown" ] }, "outlook": { "type": "string", "enum": [ "not_requested", "processing", "accepted", "success", "failed", "ready", "unknown" ] }, "meeting": { "type": "string", "enum": [ "not_requested", "processing", "accepted", "success", "failed", "ready", "unknown" ] } } }, "service_name": { "type": "string" }, "ends_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "starts_at_local": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "ends_at_local": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "customer": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "comment": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": { "type": "string" } }, "source": { "type": "string", "enum": [ "api", "form" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "service_id", "status", "starts_at", "duration_minutes", "timezone", "customer_timezone", "location", "replayed", "meeting", "delivery_status", "delivery" ] }, "Availability": { "type": "object", "properties": { "service_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" } }, "required": [ "starts_at", "ends_at" ] } } }, "required": [ "service_id", "date", "timezone", "slots" ] }, "Error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "status": { "type": "integer" } } } }, "required": [ "code", "message", "data" ] }, "BookingSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "service_id", "service_name", "status", "starts_at", "ends_at", "starts_at_local", "ends_at_local", "duration_minutes", "timezone", "customer", "source", "delivery_status" ], "properties": { "id": { "type": "integer" }, "service_id": { "type": "integer" }, "service_name": { "type": "string" }, "status": { "type": "string", "enum": [ "confirmed" ] }, "starts_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "ends_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "starts_at_local": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "ends_at_local": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "duration_minutes": { "type": "integer" }, "timezone": { "type": "string" }, "customer": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "source": { "type": "string", "enum": [ "api", "form" ] }, "delivery_status": { "type": "string", "enum": [ "processing", "complete", "needs_attention", "unknown" ] } } }, "BookingList": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "date_basis", "default_date_timezone", "scope", "bookings", "pagination" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "date_basis": { "type": "string", "const": "service_timezone" }, "default_date_timezone": { "type": "string" }, "scope": { "type": "string", "enum": [ "created_by_connection", "all" ] }, "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/BookingSummary" } }, "pagination": { "type": "object", "additionalProperties": false, "required": [ "page", "per_page", "total", "total_pages", "next_page" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "total_pages": { "type": "integer", "minimum": 0 }, "next_page": { "oneOf": [ { "type": "integer", "minimum": 2 }, { "type": "null" } ] } } } } } } } }