### List tenants: example response

Source: https://voxelbooking.com/docs/agent-api/overview

Example JSON response from the List tenants endpoint, showing a single tenant object with fields like id, name, slug, status, timezone, locale, currency, booking_pattern, and created_at.

```json
{
  "data": [
    {
      "id": "01HTENANT0000000000000000",
      "name": "Salon Bella",
      "slug": "salon-bella",
      "status": "active",
      "timezone": "Europe/Amsterdam",
      "locale": "en",
      "currency": "EUR",
      "booking_pattern": "timeslot",
      "created_at": "2026-05-04 09:30:00"
    }
  ]
}
```

--------------------------------

### GET /api/agent/v1/tenants

Source: https://voxelbooking.com/docs/agent-api/overview

Returns businesses visible to the installation. Requires the tenants:read scope.

```APIDOC
## GET /api/agent/v1/tenants

### Description
Returns businesses visible to the installation.

### Method
GET

### Endpoint
/api/agent/v1/tenants

### Parameters
#### Query Parameters
- **tenant_id** (string) - Required - Tenant ULID
- **status** (string) - Optional - Filter by status
- **limit** (integer) - Optional - Defaults to 50, maximum 100
- **offset** (integer) - Optional - Defaults to 0

### Request Example
```
curl https://your-domain.com/api/agent/v1/tenants \
  -H "Authorization: Bearer vb_your_api_key" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **id** (string) - Tenant ULID
- **name** (string) - Business name
- **slug** (string) - Public booking page slug
- **status** (string) - Tenant status
- **timezone** (string) - Tenant timezone
- **locale** (string) - Tenant locale
- **currency** (string) - Tenant currency
- **booking_pattern** (string) - `timeslot`, `resource`, `capacity`, or `event`
- **created_at** (string) - Creation time record

#### Response Example
```
{
  "data": [
    {
      "id": "01HTENANT0000000000000000",
      "name": "Salon Bella",
      "slug": "salon-bella",
      "status": "active",
      "timezone": "Europe/Amsterdam",
      "locale": "en",
      "currency": "EUR",
      "booking_pattern": "timeslot",
      "created_at": "2026-05-04 09:30:00"
    }
  ]
}
```
```

--------------------------------

### List tenants: curl request

Source: https://voxelbooking.com/docs/agent-api/overview

Sends a GET request to /api/agent/v1/tenants to retrieve businesses visible to the installation. Requires the tenants:read scope and an API key.

```bash
curl https://your-domain.com/api/agent/v1/tenants \
  -H "Authorization: Bearer vb_your_api_key" \
  -H "Accept: application/json"
```

--------------------------------

### Example curl request to Agent API schema

Source: https://voxelbooking.com/docs/agent-api/overview

Shows how to call the schema endpoint using curl.

```bash
curl https://your-domain.com/api/agent/v1/schema
```

--------------------------------

### GET /api/agent/v1/services

Source: https://voxelbooking.com/docs/agent-api/overview

Returns services for one tenant. The `tenant_id` query parameter is required.

```APIDOC
## GET /api/agent/v1/services

### Description
Returns services for one tenant. The `tenant_id` query parameter is required.

### Method
GET

### Endpoint
/api/agent/v1/services

### Parameters
#### Query Parameters
- **tenant_id** (string) - Required - Tenant ULID

### Request Example
```
curl "https://your-domain.com/api/agent/v1/services?tenant_id=01HTENANT0000000000000000" \
  -H "Authorization: Bearer vb_your_api_key" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **id** (string) - Service ULID
- **name** (string) - Service name
- **description** (string) - Optional service description
- **duration_minutes** (integer) - Duration in minutes
- **price** (number) - Optional price
- **color** (string) - Service color
- **sort_order** (integer) - Display order
- **is_active** (boolean) - Boolean active flag

#### Response Example
```json
{
  "id": "01HTENANT0000000000000000",
  "name": "Example Service",
  "description": "Optional description",
  "duration_minutes": 60,
  "price": 100.0,
  "color": "#FF5733",
  "sort_order": 1,
  "is_active": true
}
```
```

--------------------------------

### Clone the VoxelBooking repository

Source: https://voxelbooking.com/docs/getting-started/installation

Use these commands to clone the repository into your web root via HTTPS. The vendor directory is included, so no additional dependency installation is required.

```bash
cd /path/to/your/webroot
git clone https://github.com/NowSquare/VoxelBooking.git .
```

--------------------------------

### GET /api/agent/v1/tenants

Source: https://voxelbooking.com/docs/agent-api/overview

Lists businesses (tenants) in the system. Requires authentication and the 'tenants:read' scope.

```APIDOC
## GET /api/agent/v1/tenants

### Description
Lists businesses (tenants) in the system. Requires authentication and the 'tenants:read' scope.

### Method
GET

### Endpoint
/api/agent/v1/tenants

### Auth
Required

### Scope
'tenants:read'

### Response
#### Success Response (200)
List of businesses (tenants). Any other response: error.
```

--------------------------------

### GET /api/agent/v1/services

Source: https://voxelbooking.com/docs/agent-api/overview

Lists services for one business. This endpoint requires authentication and the 'services:read' scope.

```APIDOC
## GET /api/agent/v1/services

### Description
Lists services for one business. Requires authentication and the 'services:read' scope.

### Method
GET

### Endpoint
/api/agent/v1/services

### Auth
Required
### Scope
'services:read'

### Response
#### Success Response (200)
List of services for a business. Additional error information omitted.
```

--------------------------------

### GET /api/agent/v1/bookings

Source: https://voxelbooking.com/docs/agent-api/overview

Returns bookings for one tenant. The tenant_id query parameter is required. Requires the bookings:read scope.

```APIDOC
## GET /api/agent/v1/bookings

### Description
Returns bookings for one tenant. The `tenant_id` query parameter is required.

### Method
GET

### Endpoint
/api/agent/v1/bookings

### Parameters
#### Query Parameters
- **tenant_id** (string) - Required - Tenant ULID
- **status** (string) - Optional - Filter by status
- **limit** (integer) - Optional - Defaults to 50, maximum 100
- **offset** (integer) - Optional - Defaults to 0

### Request Example
```
curl "https://your-domain.com/api/agent/v1/bookings?tenant_id=01HTENANT0000000000000000&limit=25" \
  -H "Authorization: Bearer vb_your_api_key" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **id** (string) - Booking id
- **tenant_id** (string) - Tenant id
- **service_id** (string) - Service id
- **staff_id** (string) - Staff id
- **customer_id** (string) - Customer id
- **start_time** (string) - Start time
- **end_time** (string) - End time
- **status** (string) - Status
- **source** (string) - Source
- **consent** (boolean) - Consent flag
- **created_at** (string) - Creation time record

#### Response Example
```
{
  "data": [
    {
      "id": "01HBOOKING0000000000000000",
      "tenant_id": "01HTENANT0000000000000000",
      "service_id": "01HSERVICE0000000000000000",
      "staff_id": "01HSTAFF0000000000000000",
      "customer_id": "01HCUSTOMER0000000000000000",
      "start_time": "2026-05-04 10:00:00",
      "end_time": "2026-05-04 11:00:00",
      "status": "confirmed",
      "source": "api",
      "consent": true,
      "created_at": "2026-05-04 09:30:00"
    }
  ]
}
```
```

--------------------------------

### List bookings: curl request

Source: https://voxelbooking.com/docs/agent-api/overview

Sends a GET request to /api/agent/v1/bookings with a required tenant_id query parameter. Requires the bookings:read scope and an API key.

```bash
curl "https://your-domain.com/api/agent/v1/bookings?tenant_id=01HTENANT0000000000000000&limit=25" \
  -H "Authorization: Bearer vb_your_api_key" \
  -H "Accept: application/json"
```

--------------------------------

### GET /api/agent/v1/availability

Source: https://voxelbooking.com/docs/agent-api/overview

Returns available staff schedule rows for one tenant. The `tenant_id` query parameter is required.

```APIDOC
## GET /api/agent/v1/availability

### Description
Returns available staff schedule rows for one tenant. The `tenant_id` query parameter is required.

### Method
GET

### Endpoint
/api/agent/v1/availability

### Parameters
#### Query Parameters
- **tenant_id** (string) - Required - Tenant ULID

### Request Example
```
curl "https://your-domain.com/api/agent/v1/availability?tenant_id=01HTENANT0000000000000000" \
  -H "Authorization: Bearer vb_your_api_key" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **staff_id** (string) - Staff ULID or null
- **day_of_week** (integer) - Integer weekday
- **start_time** (string) - Start time
- **end_time** (string) - End time
- **is_available** (boolean) - Returned rows are available

#### Response Example
```json
{
  "staff_id": "01HTENANT0000000000000000",
  "day_of_week": 1,
  "start_time": "09:00",
  "end_time": "17:00",
  "is_available": true
}
```
```

--------------------------------

### GET /api/agent/v1/bookings

Source: https://voxelbooking.com/docs/agent-api/overview

Lists bookings for one business. This endpoint requires authentication and the 'bookings:read' scope. The exact query parameters are not specified in the source.

```APIDOC
## GET /api/agent/v1/bookings

### Description
Lists bookings for one business. Requires authentication and the 'bookings:read' scope.

### Method
GET

### Endpoint
/api/agent/v1/bookings

### Auth
Required
### Scope
'bookings:read'

### Response
#### Success Response (200)
List of bookings for a business. Any other details/error omitted.
```

--------------------------------

### GET /api/agent/v1/schema

Source: https://voxelbooking.com/docs/agent-api/overview

Returns the OpenAPI 3.0.3 schema for the Agent API. This endpoint is unauthenticated and has no required scope.

```APIDOC
## GET /api/agent/v1/schema

### Description
Returns the OpenAPI 3.0.3 schema for the Agent API.

### Method
GET

### Endpoint
/api/agent/v1/schema

### Parameters
None

### Response
#### Success Response (200)
OpenAPI 3.0.3 schema document.
```

--------------------------------

### GET /api/agent/v1/availability

Source: https://voxelbooking.com/docs/agent-api/overview

Lists available staff schedule rows for one business. This endpoint requires authentication and the 'availability:read' scope.

```APIDOC
## GET /api/agent/v1/availability

### Description
Lists available staff schedule rows for one business. Requires authentication and the 'availability:read' scope.

### Method
GET

### Endpoint
/api/agent/v1/availability

### Auth
Required
### Scope
'availability:read'

### Response
#### Success Response (200)
List of available staff schedule rows for one business. Error details omitted.
```

--------------------------------

### Activate demo mode

Source: https://voxelbooking.com/docs/admin-panel/demo-mode

Create an empty .demo file in the application root to enable demo mode. The file must be zero bytes.

```bash
touch /path/to/voxelbooking/.demo
```

--------------------------------

### Run demo reset script

Source: https://voxelbooking.com/docs/admin-panel/demo-mode

Execute the reset script to clear the database and re-seed the showcase dataset. Use the --dry flag to preview changes without applying them.

```bash
# Full reset (drops tables, migrates, reseeds, clears sessions)
php scripts/reset-demo.php

# Preview only (no changes)
php scripts/reset-demo.php --dry
```

--------------------------------

### Automate demo reset with cron

Source: https://voxelbooking.com/docs/admin-panel/demo-mode

Schedule the reset script to run daily using a crontab entry. Ensure the path to the PHP binary and the application directory are correct for your environment.

```bash
# Example crontab entry - runs daily at 3:00 AM
0 3 * * * /usr/bin/php /path/to/voxelbooking/scripts/reset-demo.php >> /path/to/voxelbooking/storage/logs/demo-reset.log 2>&1
```

--------------------------------

### Domain allowlist configuration

Source: https://voxelbooking.com/docs/customization/embed

A list of domains authorized to host the booking widget. Enter one domain per line, using wildcards like *.example.com for subdomains.

```text
example.com
shop.mybusiness.com
```

--------------------------------

### List services API request

Source: https://voxelbooking.com/docs/agent-api/overview

Retrieves services for a specific tenant using the tenant_id query parameter.

```bash
curl "https://your-domain.com/api/agent/v1/services?tenant_id=01HTENANT0000000000000000" \
  -H "Authorization: Bearer vb_your_api_key" \
  -H "Accept: application/json"
```

--------------------------------

### Pin a version with git checkout

Source: https://voxelbooking.com/docs/getting-started/updating

Pin a specific VoxelBooking version by fetching Git tags and checking out a tag like v1.0.0. Run from your webroot; use `git checkout main` to return to tracking the latest.

```shell
cd /path/to/your/webroot
git fetch --tags
git checkout v1.0.0

```

--------------------------------

### List availability API request

Source: https://voxelbooking.com/docs/agent-api/overview

Retrieves available staff schedule rows for a specific tenant.

```bash
curl "https://your-domain.com/api/agent/v1/availability?tenant_id=01HTENANT0000000000000000" \
  -H "Authorization: Bearer vb_your_api_key" \
  -H "Accept: application/json"
```

--------------------------------

### Error response: Missing tenant_id

Source: https://voxelbooking.com/docs/agent-api/overview

Returned when the required tenant_id query parameter is missing.

```json
{
  "error": "validation",
  "message": "tenant_id is required"
}
```

--------------------------------

### Nginx rewrite rule for VoxelBooking clean URLs

Source: https://voxelbooking.com/docs/troubleshooting/common-issues

Add this rewrite rule to your Nginx config to fix clean URL routing for VoxelBooking. Nginx ignores .htaccess and its default try_files rule falls back to index.php when it cannot find the file, causing the homepage to be served for /features and /pricing.

```nginx
location / {
    try_files $uri $uri/ /public/index.php?$query_string;
}
```

--------------------------------

### Error response: Invalid or expired key

Source: https://voxelbooking.com/docs/agent-api/overview

Returned when the provided API key is invalid, expired, or inactive.

```json
{
  "error": "unauthorized",
  "message": "Invalid or expired API key."
}
```

--------------------------------

### Error response: Missing Bearer token

Source: https://voxelbooking.com/docs/agent-api/overview

Returned when the Authorization header is missing or invalid.

```json
{
  "error": "unauthorized",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"
}
```

--------------------------------

### Fetch Public OpenAPI Schema with Curl

Source: https://voxelbooking.com/docs/agent-api/overview

Public endpoint to retrieve the OpenAPI 3.0.3 document before authenticating. Returns paths, parameters, response schemas, and required scopes.

```bash
curl https://your-domain.com/api/agent/v1/schema

```

--------------------------------

### Base URL for Agent API

Source: https://voxelbooking.com/docs/agent-api/overview

All Agent API routes live under this base path.

```plaintext
/api/agent/v1
```

--------------------------------

### Embed widget script

Source: https://voxelbooking.com/docs/customization/branding

Generate an embed script to place the booking widget on any external website. The widget inherits the business's branding and matches the booking page appearance.

```html
<script src="https://your-domain.com/embed/your-slug.js"></script>
```

--------------------------------

### Error response: Missing scope

Source: https://voxelbooking.com/docs/agent-api/overview

Returned when the API key lacks the required scope for the requested route.

```json
{
  "error": "forbidden",
  "message": "This route requires the 'bookings:read' scope."
}
```

--------------------------------

### Rate Limit Exceeded Error Response

Source: https://voxelbooking.com/docs/agent-api/overview

Returned when the 60 requests per minute limit is reached. Includes retry_after value in seconds.

```JSON
{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Please wait before making more requests.",
  "retry_after": 60
}

```

--------------------------------

### List tenants: required scope

Source: https://voxelbooking.com/docs/agent-api/overview

The OAuth scope required to call the List tenants endpoint.

```text
tenants:read
```

--------------------------------

### Nginx fastcgi_param for Authorization header

Source: https://voxelbooking.com/docs/troubleshooting/common-issues

Add this line inside your `location ~ \.php$` block to fix Agent API 401 errors on Nginx. Nginx strips the Authorization header before forwarding requests to PHP-FPM, causing a 'Missing Authorization header' error even with a valid API key.

```nginx
fastcgi_param HTTP_AUTHORIZATION $http_authorization;
```

--------------------------------

### Embed script tag

Source: https://voxelbooking.com/docs/customization/embed

The script tag used to inject the booking button into the host website. Place this before the closing </body> tag.

```html
<script src="https://your-domain.com/embed/business-slug.js" defer></script>
```

--------------------------------

### List availability required scope

Source: https://voxelbooking.com/docs/agent-api/overview

The required scope for the list availability endpoint.

```text
availability:read
```

--------------------------------

### List services required scope

Source: https://voxelbooking.com/docs/agent-api/overview

The required scope for the list services endpoint.

```text
services:read
```

--------------------------------

### List bookings: required scope

Source: https://voxelbooking.com/docs/agent-api/overview

The OAuth scope required to call the List bookings endpoint.

```text
bookings:read
```

--------------------------------

### Authentication Header: Authorization Bearer Token

Source: https://voxelbooking.com/docs/agent-api/overview

Required request header for authenticated Agent API routes. Use this header in every authenticated request. The API key must be supplied as a Bearer token.

```HTTP
Authorization: Bearer vb_your_api_key
Accept: application/json

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.