API Overview

The Basefloor API is a RESTful JSON API served by hms-core (Ruby on Rails). All frontend applications communicate exclusively through this API.

Base URL

Authentication

The API uses token-based authentication. After logging in, every subsequent request must include the token in the Authorization header:

Authorization: Bearer <your_token>

Login

POST /api/v1/users/sessions
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your_password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": 1,
    "email": "[email protected]",
    "role": "manager",
    "hotel_chain_id": 5
  }
}

Logout

DELETE /api/v1/users/sessions
Authorization: Bearer <token>

Multi-Tenancy Headers

Every API request is automatically scoped to a hotel chain. The chain is resolved from the subdomain of the request origin. When calling from a frontend on khyber.hms.com, the API automatically scopes all queries to the Khyber chain.

For direct API testing (e.g., with Bruno or curl), pass the chain slug via the X-Hotel-Chain header:

X-Hotel-Chain: khyber

Request Format

• All request bodies must be application/json
• Dates use ISO 8601 format: 2025-06-15
• Times use UTC: 2025-06-15T14:00:00Z

Response Format

Successful responses return a JSON object with a data key:

{
  "data": {
    "id": 42,
    "type": "booking",
    "attributes": { ... }
  }
}

List responses include pagination metadata:

{
  "data": [ ... ],
  "meta": {
    "total": 120,
    "page": 1,
    "per_page": 25
  }
}

Error Format

Errors return an errors array:

{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "detail": "Check-out date must be after check-in date"
    }
  ]
}

HTTP Status Codes

Key Endpoints Reference

Properties

Bookings

Guests

Users

API Collection

A full Bruno API collection is available in the bruno/ directory of the hms-core repository. Import it into Bruno to explore and test all endpoints interactively.