Tamu API Documentation

Build integrations with the Tamu booking platform using our REST API

Overview

The Tamu API allows you to programmatically manage properties, rooms, availability, and bookings. All API endpoints are RESTful and return JSON responses.

API Key Auth

Secure key-based authentication

Rate Limited

100/min read, 20/min write

Scoped Access

Read, write, admin scopes

Authentication

All API requests require an API key passed in the X-API-Key header.

curl -X GET "https://api.tamuhq.com/api/v1/properties" \
  -H "X-API-Key: tamu_live_xxxxxxxxxxxxxxxxxxxx"

Keep your API key secure

Never expose your API key in client-side code or public repositories. Revoke and regenerate keys if you suspect they have been compromised.

Base URL

https://api.tamuhq.com/api/v1

Response Format

All responses follow a consistent format:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-01-05T10:30:00.000Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field: check_in",
    "details": { "errors": ["check_in is required"] }
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-01-05T10:30:00.000Z"
  }
}

Endpoints

Properties

GET/api/v1/propertiesread

List all properties

Parameters

status(string)- Filter by status (default: active)

city(string)- Filter by city name

page(integer)- Page number (default: 1)

limit(integer)- Items per page (max: 100)

GET/api/v1/properties/:idread

Get a single property by ID

POST/api/v1/propertieswrite

Create a new property

Request Body

{
  "name": "Beach Resort",
  "slug": "beach-resort",
  "city": "Langkawi",
  "country": "MY"
}

PATCH/api/v1/properties/:idwrite

Update a property

Rooms

GET/api/v1/roomsread

List all rooms

Parameters

property_id(uuid)- Filter by property

status(string)- Filter by status

min_guests(integer)- Minimum guest capacity

GET/api/v1/rooms/:idread

Get a single room by ID

POST/api/v1/roomswrite

Create a new room

Request Body

{
  "property_id": "uuid",
  "name": "Deluxe Suite",
  "slug": "deluxe-suite",
  "base_rate": 350,
  "max_guests": 4
}

PATCH/api/v1/rooms/:idwrite

Update a room

Availability

GET/api/v1/availabilityread

Check availability for a room

Parameters

room_id(uuid)- Room ID (required)

check_in(date)- Check-in date YYYY-MM-DD (required)

check_out(date)- Check-out date YYYY-MM-DD (required)

Example Response

{
  "available": true,
  "room_id": "uuid",
  "check_in": "2024-02-15",
  "check_out": "2024-02-18",
  "nights": 3,
  "available_units": 2,
  "pricing": {
    "estimated_total": 1050,
    "currency": "MYR",
    "base_rate": 350,
    "weekend_rate": 400
  }
}

POST/api/v1/availabilityread

Bulk check availability for multiple rooms

Request Body

{
  "room_ids": ["uuid1", "uuid2"],
  "check_in": "2024-02-15",
  "check_out": "2024-02-18"
}

Bookings

GET/api/v1/bookingsread

List all bookings

Parameters

property_id(uuid)- Filter by property

status(string)- Filter by status

from_date(date)- Filter from check-in date

to_date(date)- Filter to check-in date

guest_email(string)- Filter by guest email

GET/api/v1/bookings/:idread

Get a single booking (by ID or booking_ref)

POST/api/v1/bookingswrite

Create a new booking

Request Body

{
  "room_id": "uuid",
  "check_in": "2024-02-15",
  "check_out": "2024-02-18",
  "guest_name": "John Doe",
  "guest_email": "john@example.com",
  "guest_phone": "+60123456789",
  "adults": 2,
  "children": 1,
  "special_requests": "Early check-in if possible"
}

PATCH/api/v1/bookings/:idwrite

Update a booking

DELETE/api/v1/bookings/:idwrite

Cancel a booking

Parameters

reason(string)- Cancellation reason

Rate Limiting

API requests are rate limited to ensure fair usage:

Read operations: 100 requests per minute
Write operations: 20 requests per minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704450000000

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`BAD_REQUEST`	400	Invalid request parameters
`VALIDATION_ERROR`	400	Request body validation failed
`UNAVAILABLE`	409	Room not available for dates
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

SDKs & Libraries

Official SDKs are coming soon. In the meantime, you can use any HTTP client to interact with the API.