Bookings API — Resources, Availability, and Reservations

The bookings API lets you embed scheduling into any external surface — a website, a mobile app, or an AI agent. You list available resources, query open slots for a date range, and confirm a booking by passing a slot ID back to the create endpoint. Slot IDs are opaque and encode both the resource and the start time, so you never need to reconstruct them.

Required scopes

Operation	Required scope
List resources, check availability, list bookings	`bookings.read`
Create and cancel bookings	`bookings.manage`
Create and update resources	`bookings.resources.manage`

Resource types

A bookable resource can represent any schedulable entity: location · service · room · equipment · person

Booking statuses

Status	Meaning
`confirmed`	Booking is active.
`cancelled`	Booking was cancelled.
`no_show`	Guest did not appear.
`completed`	Booking has been completed.

List resources

GET /api/bookings/resources Returns all active bookable resources for the tenant.

Query parameters

string

Filter by resource type: location, service, room, equipment, or person.

string

Search by resource name.

boolean

default:"false"

When true, includes resources where isActive is false.

integer

Maximum number of results.

integer

default:"0"

Results to skip for pagination.

Response

{
  "data": [
    {
      "id": "res-uuid-001",
      "type": "location",
      "name": "Main Campus Tour",
      "slug": "main-campus-tour",
      "description": "Guided tour of the main campus.",
      "addressLine1": "500 Campus Drive",
      "city": "Salt Lake City",
      "state": "UT",
      "postalCode": "84101",
      "timezone": "America/Denver",
      "defaultDurationMinutes": 60,
      "maxConcurrent": 10,
      "isActive": true,
      "published": true
    }
  ]
}

curl -X GET "https://app.novala.ai/api/bookings/resources?type=location" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.novala.ai/api/bookings/resources?type=location',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { data } = await response.json();

Get available slots

GET /api/bookings/resources/{id}/availability Returns available time slots for a resource within a date range. Use this before creating a booking to present real-time availability to a user.

Path parameters

string

required

UUID of the bookable resource.

Query parameters

string

Start of the date range (ISO 8601, for example 2024-08-01 or 2024-08-01T00:00:00Z). Defaults to now.

string

End of the date range (ISO 8601). Defaults to 7 days from from.

Response

{
  "resourceId": "res-uuid-001",
  "slots": [
    {
      "slotId": "cmVzLXV1aWQtMDAxXzIwMjQtMDgtMDFUMDk6MDA6MDBa",
      "startsAt": "2024-08-01T09:00:00.000Z",
      "endsAt": "2024-08-01T10:00:00.000Z",
      "remaining": 8
    },
    {
      "slotId": "cmVzLXV1aWQtMDAxXzIwMjQtMDgtMDFUMTA6MDA6MDBa",
      "startsAt": "2024-08-01T10:00:00.000Z",
      "endsAt": "2024-08-01T11:00:00.000Z",
      "remaining": 10
    }
  ]
}

remaining reflects the number of additional bookings that can be made for the slot, based on maxConcurrent.

Slot IDs are opaque strings. Do not parse or construct them manually — always pass back the exact slotId value returned by this endpoint when creating a booking.

curl -X GET "https://app.novala.ai/api/bookings/resources/res-uuid-001/availability?from=2024-08-01&to=2024-08-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({ from: '2024-08-01', to: '2024-08-07' });
const response = await fetch(
  `https://app.novala.ai/api/bookings/resources/res-uuid-001/availability?${params}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { slots } = await response.json();

List bookings

GET /api/bookings Returns a list of bookings for the tenant, with optional filters.

Query parameters

string

Filter by resource UUID.

string

Filter by booking status: confirmed, cancelled, no_show, completed.

string

Filter by the lead UUID associated with the booking.

string

Return bookings starting on or after this date (ISO 8601).

string

Return bookings starting on or before this date (ISO 8601).

integer

Maximum number of results.

integer

default:"0"

Offset for pagination.

Create a booking

POST /api/bookings Confirms a booking for a slot. The slot is validated against the resource’s operating hours and closures at write time. If the slot is no longer available, the request returns 409 Conflict.

Request body

string

required

Opaque slot ID obtained from the availability endpoint.

string

required

Guest’s first name.

string

required

Guest’s last name.

string

required

Guest’s email address. Used for confirmation emails.

string

Guest’s phone number.

string

Additional notes from the guest.

string

What the guest is interested in (for example, a specific program or service).

string

default:"api"

Attribution for the booking source.

Response

Returns 201 Created with the confirmed booking object. Returns 409 Conflict if the slot has been taken.

curl -X POST https://app.novala.ai/api/bookings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slotId": "cmVzLXV1aWQtMDAxXzIwMjQtMDgtMDFUMDk6MDA6MDBa",
    "firstName": "Morgan",
    "lastName": "Lee",
    "email": "morgan.lee@example.com",
    "phone": "+15559876543",
    "interest": "Fall semester enrollment"
  }'

// 1. Fetch availability
const availRes = await fetch(
  'https://app.novala.ai/api/bookings/resources/res-uuid-001/availability?from=2024-08-01',
  { headers: { Authorization: `Bearer ${apiKey}` } }
);
const { slots } = await availRes.json();
const slot = slots[0]; // pick a slot to show the user

// 2. Confirm the booking
const bookRes = await fetch('https://app.novala.ai/api/bookings', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    slotId: slot.slotId,
    firstName: 'Morgan',
    lastName: 'Lee',
    email: 'morgan.lee@example.com',
    interest: 'Fall semester enrollment',
  }),
});

if (bookRes.status === 409) {
  // Slot was taken between availability check and booking
  throw new Error('Slot no longer available');
}
const booking = await bookRes.json();

Get a booking

GET /api/bookings/{id} Retrieves a single booking by ID.

Path parameters

string

required

UUID of the booking.

Response

Returns 200 OK with { "booking": { booking object } }.

Cancel a booking

DELETE /api/bookings/{id} Cancels a booking. The booking record is retained; its status changes to cancelled. Returns 404 if the booking is already cancelled.

Path parameters

string

required

UUID of the booking to cancel.

Response

Returns 200 OK with { "success": true }.

curl -X DELETE https://app.novala.ai/api/bookings/booking-uuid-001 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://app.novala.ai/api/bookings/booking-uuid-001', {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` },
});
// 200 { success: true }

Overview

Endpoints

Bookings API — Resources, Availability, and Reservations

Required scopes

Resource types

Booking statuses

List resources

Query parameters

Response

Get available slots

Path parameters

Query parameters

Response

List bookings

Query parameters

Create a booking

Request body

Response

Get a booking

Path parameters

Response

Cancel a booking

Path parameters

Response

​Required scopes

​Resource types

​Booking statuses

​List resources

​Query parameters

​Response

​Get available slots

​Path parameters

​Query parameters

​Response

​List bookings

​Query parameters

​Create a booking

​Request body

​Response

​Get a booking

​Path parameters

​Response

​Cancel a booking

​Path parameters

​Response

Required scopes

Resource types

Booking statuses

List resources

Query parameters

Response

Get available slots

Path parameters

Query parameters

Response

List bookings

Query parameters

Create a booking

Request body

Response

Get a booking

Path parameters

Response

Cancel a booking

Path parameters

Response