Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.novala.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

OperationRequired scope
List resources, check availability, list bookingsbookings.read
Create and cancel bookingsbookings.manage
Create and update resourcesbookings.resources.manage

​
Resource types

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

​
Booking statuses

StatusMeaning
confirmedBooking is active.
cancelledBooking was cancelled.
no_showGuest did not appear.
completedBooking has been completed.

​
List resources

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

​
Query parameters

​
type
string
Filter by resource type: location, service, room, equipment, or person.
​
query
string
Search by resource name.
​
includeInactive
boolean
default:"false"
When true, includes resources where isActive is false.
​
limit
integer
Maximum number of results.
​
offset
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"

​
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

​
id
string
required
UUID of the bookable resource.

​
Query parameters

​
from
string
Start of the date range (ISO 8601, for example 2024-08-01 or 2024-08-01T00:00:00Z). Defaults to now.
​
to
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"

​
List bookings

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

​
Query parameters

​
resourceId
string
Filter by resource UUID.
​
status
string
Filter by booking status: confirmed, cancelled, no_show, completed.
​
leadId
string
Filter by the lead UUID associated with the booking.
​
from
string
Return bookings starting on or after this date (ISO 8601).
​
to
string
Return bookings starting on or before this date (ISO 8601).
​
limit
integer
Maximum number of results.
​
offset
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

​
slotId
string
required
Opaque slot ID obtained from the availability endpoint.
​
firstName
string
required
Guest’s first name.
​
lastName
string
required
Guest’s last name.
​
email
string
required
Guest’s email address. Used for confirmation emails.
​
phone
string
Guest’s phone number.
​
notes
string
Additional notes from the guest.
​
interest
string
What the guest is interested in (for example, a specific program or service).
​
source
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"
  }'

​
Get a booking

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

​
Path parameters

​
id
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

​
id
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"