API Reference

Complete REST API reference for the Booking Management platform.

Base URL

{YOUR_API_URL}/api

All endpoints are prefixed with /api. Replace {YOUR_API_URL} with your deployment URL (e.g. https://api.example.com).

Authentication

The API uses PASETO V4 tokens for authentication. Include the token in the Authorization header:

Authorization: Bearer <token>

Tokens are obtained via the Auth API login endpoint. Most endpoints require a valid token unless noted otherwise.

Standard Response Format

All responses follow a consistent JSON structure:

{
  "success": true,
  "data": {},
  "message": "Operation completed successfully"
}

Field	Type	Description
success	boolean	Whether the request succeeded
data	any	Response payload (object, array, or null)
message	string	Human-readable status message

Pagination

List endpoints support pagination via query parameters:

GET /api/bookings/:orgId/list?page=1&limit=20

Parameter	Type	Default	Description
page	number	1	Page number (1-indexed)
limit	number	20	Items per page

Paginated responses include metadata:

{
  "success": true,
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Error Codes

Status Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Insufficient permissions for the requested action
404	Not Found	Resource does not exist
500	Internal Server Error	Unexpected server-side failure

Error Response Example

{
  "success": false,
  "message": "Validation failed: email is required"
}

Rate Limiting

API requests are rate-limited per IP address. When the limit is exceeded, the server responds with 429 Too Many Requests.

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Timestamp (epoch seconds) when the window resets

{
  "success": false,
  "message": "Too many requests, please try again later"
}

Endpoint Groups

Group	Prefix	Description
Auth	/api/auth	Authentication, token management, password reset
Bookings	/api/bookings	Booking lifecycle — create, update, check-in, checkout
Invoices	/api/invoice	Invoice creation, listing, and updates
Payments	/api/payment	Payment recording and management
Quotes	/api/quote	Quotation creation, listing, updates, and deletion