VoxelBooking

https://voxelbooking.com/docs
Admin
VoxelBooking is an open-source, self-hosted multi-business booking system that supports...
Tokens:26,000
Snippets:327
Trust Score:4.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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.
```

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

### 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
```

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

### 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.
```

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

### 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

```

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

### 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.
```

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

### 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"
}
```
Tokens:
Raw