API Reference

The Bookwell API allows you to integrate booking functionality into your own applications. This documentation covers authentication, endpoints, and best practices.

Overview

The Bookwell API is a RESTful API that uses:

• JSON for request and response bodies
• Bearer token authentication
• Standard HTTP status codes
• Rate limiting for fair usage

Base URL

All API requests use this base URL:

https://api.bookwell.app/v1

For sandbox/testing:

https://api.sandbox.bookwell.app/v1

Quick Start

curl https://api.bookwell.app/v1/services \
  -H "Authorization: Bearer YOUR_API_KEY"

API Documentation

Core Concepts

Resources

The API provides access to these resources:

Request Format

Send JSON in request bodies:

{
  "service_id": "srv_123abc",
  "customer_email": "customer@example.com",
  "start_time": "2025-01-15T10:00:00Z"
}

Response Format

Responses are JSON with this structure:

{
  "data": {
    "id": "apt_456def",
    "service_id": "srv_123abc",
    "status": "confirmed"
  },
  "meta": {
    "request_id": "req_789ghi"
  }
}

Pagination

List endpoints support pagination:

curl "https://api.bookwell.app/v1/appointments?page=2&per_page=20"

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

Filtering

Many endpoints support filtering:

curl "https://api.bookwell.app/v1/appointments?status=confirmed&date_from=2025-01-01"

Rate Limiting

The API has rate limits to ensure fair usage:

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

Errors

Errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "The service_id is required",
    "details": {
      "field": "service_id"
    }
  }
}

See Error Handling for all error codes.

SDKs and Libraries

Official libraries are available for:

• JavaScript/TypeScript - npm install @bookwell/sdk
• Python - pip install bookwell
• PHP - composer require bookwell/bookwell-php
• Ruby - gem install bookwell

Testing

Sandbox Environment

Use the sandbox for development:

• Test API key from dashboard
• No real charges processed
• Data is reset periodically

Test Data

The sandbox includes test data:

• Sample services
• Test customers
• Mock appointments

Support

API Status

Check API status at: status.bookwell.app

Getting Help

• Review this documentation
• Check the FAQ
• Contact developer support