M4 API Reference

The M4 Reporting API provides endpoints for dashboard metrics, listings, reservations, and data export.

Base URL

Production: https://m4.inspiringlivingsolutions.com/api
Development: http://localhost:3000/api

Authentication

Requires Clerk session authentication.

Rate Limiting

Endpoint Type	Limit
Dashboard	120 req/min
Listings	60 req/min
Sync	5 req/min
Default	60 req/min

Endpoints

Dashboard

Get Metrics

GET /dashboard/metrics

Query Parameters:

Parameter	Type	Description
startDate	string	Start date (YYYY-MM-DD)
endDate	string	End date (YYYY-MM-DD)
listingIds	string	Comma-separated IDs

Response:

{
  "revenue": {
    "total": 1250000,
    "previous": 1100000,
    "change": 13.6
  },
  "occupancy": {
    "rate": 72.5,
    "previous": 68.2,
    "change": 4.3
  },
  "adr": {
    "value": 8500,
    "previous": 8200,
    "change": 3.7
  },
  "bookings": {
    "count": 45,
    "previous": 42,
    "change": 7.1
  },
  "revpar": {
    "value": 6163,
    "previous": 5594,
    "change": 10.2
  }
}

Get Charts

GET /dashboard/charts

Query Parameters:

Parameter	Type	Description
type	string	revenue, occupancy
period	string	daily, weekly, monthly
startDate	string	Start date
endDate	string	End date

Response:

{
  "labels": ["Jan", "Feb", "Mar"],
  "datasets": [
    {
      "label": "Revenue",
      "data": [450000, 520000, 480000]
    }
  ]
}

Get Occupancy

GET /dashboard/occupancy

Response:

{
  "calendar": [
    {
      "date": "2024-01-15",
      "occupancy": 85,
      "bookedNights": 17,
      "availableNights": 20
    }
  ],
  "byProperty": [
    {
      "listingId": "uuid",
      "name": "Villa Sunrise",
      "occupancy": 78
    }
  ]
}

Get Reservations

GET /dashboard/reservations

Query Parameters:

Parameter	Type	Description
limit	number	Number of results
status	string	Filter by status

---

Listings

List Listings

GET /listings

Response:

{
  "data": [
    {
      "id": "uuid",
      "hostifyId": "12345",
      "name": "Villa Sunrise",
      "status": "ACTIVE",
      "bedrooms": 4,
      "location": "Koh Samui",
      "metrics": {
        "revenue": 850000,
        "occupancy": 72,
        "bookings": 15
      }
    }
  ]
}

Get Listing

GET /listings/:id

---

Reservations

List Reservations

GET /reservations

Query Parameters:

Parameter	Type	Description
page	number	Page number
limit	number	Items per page
listingId	string	Filter by listing
status	string	Filter by status
startDate	string	Check-in from
endDate	string	Check-in to
channel	string	Booking channel

Response:

{
  "data": [
    {
      "id": "uuid",
      "hostifyId": "RES-12345",
      "guestName": "John Smith",
      "listing": { "id": "uuid", "name": "Villa Sunrise" },
      "checkIn": "2024-01-15",
      "checkOut": "2024-01-20",
      "nights": 5,
      "channel": "AIRBNB",
      "totalAmount": 42500,
      "netAmount": 36125,
      "status": "CONFIRMED"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 150 }
}

Get Reservation

GET /reservations/:id

---

Sync

Trigger Sync

POST /sync/trigger

Body:

{
  "type": "full",
  "entities": ["listings", "reservations"]
}

Response:

{
  "syncId": "uuid",
  "status": "STARTED",
  "startedAt": "2024-01-15T10:00:00Z"
}

Get Sync Status

GET /sync/status/:syncId

---

Export

Export Data

POST /export

Body:

{
  "type": "reservations",
  "format": "excel",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "listingIds": ["uuid1", "uuid2"]
}

Response:

{
  "exportId": "uuid",
  "status": "PROCESSING"
}

Download Export

GET /export/:exportId/download

---

Health

Health Check

GET /health

Response:

{
  "status": "healthy",
  "database": "connected",
  "hostify": "connected",
  "timestamp": "2024-01-15T10:00:00Z"
}

---

Caching

Endpoint	Cache Duration
Listings	10 minutes
Reservations	2 minutes
Dashboard	5 minutes

Error Responses

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}