MX Booking Bot - HTTP API Documentation

Base URL: https://optimistic-alligator-723.convex.site

All endpoints return JSON and support CORS.

---

Room Endpoints

Get Room Next Booking

Check if a room has upcoming bookings from the current time.

GET /api/room/next-booking

Parameters

Parameter	Type	Required	Default	Description
room	string	Yes	-	Room name (URL encoded if contains spaces)
currentTime	string	No	Bangkok now	Time override in HH:MM format
sprint	string	No	Auto-detect	Sprint filter

Example Request

# Basic usage - only room name required
curl "https://optimistic-alligator-723.convex.site/api/room/next-booking?room=meeting%20M"

# With time override (for testing)
curl "https://optimistic-alligator-723.convex.site/api/room/next-booking?room=PO%20Room&currentTime=08:00"

# With sprint filter
curl "https://optimistic-alligator-723.convex.site/api/room/next-booking?room=mocap%20M&sprint=3"

Response - Has Next Booking

{
  "success": true,
  "room": "meeting M",
  "queriedAt": "2026-01-28T11:45:45+07:00",
  "currentTime": "11:45",
  "thaiDay": "วันพุธ",
  "sprint": "3",
  "hasNextBooking": true,
  "nextBooking": {
    "userStory": "ทำแผนMile75 Management Pipeline",
    "startTime": "14:00",
    "endTime": "15:00",
    "startsIn": {
      "minutes": 135,
      "display": "2 hours 15 minutes"
    },
    "coordinator": "science.wy",
    "milestone": "74",
    "assignees": [
      { "username": "alkane.pk", "discordId": "484559744837746694" },
      { "username": "black.ct", "discordId": "1252939460316762113" },
      { "username": "peem.cp", "discordId": "817336364210847756" },
      { "username": "mine.ns", "discordId": "981853925655347261" },
      { "username": "science.wy", "discordId": "1333706782077616149" }
    ]
  },
  "roomFreeUntil": "14:00"
}

Response - No Booking

{
  "success": true,
  "room": "PO Room",
  "queriedAt": "2026-01-28T17:30:00+07:00",
  "currentTime": "17:30",
  "thaiDay": "วันพุธ",
  "sprint": null,
  "hasNextBooking": false,
  "nextBooking": null,
  "message": "No upcoming bookings for this room today"
}

Response Fields

Field	Type	Description
success	boolean	Request succeeded
room	string	Room name queried
queriedAt	string	ISO 8601 timestamp with Bangkok timezone
currentTime	string	Time used for query (HH:MM)
thaiDay	string	Thai day name (e.g., วันพุธ)
sprint	string|null	Sprint of the booking (null if no bookings)
hasNextBooking	boolean	Whether room has upcoming booking
nextBooking	object|null	Booking details (see below)
roomFreeUntil	string	Time when room becomes occupied (HH:MM)
message	string	Human-readable status (when no booking)

Next Booking Object

Field	Type	Description
userStory	string	Booking topic/task name
startTime	string	Start time (HH:MM)
endTime	string	End time (HH:MM)
startsIn.minutes	number	Minutes until booking starts
startsIn.display	string	Human-readable time (e.g., "2 hours 15 minutes")
coordinator	string	Coordinator username
milestone	string|null	Milestone identifier
assignees	array	List of assigned users
assignees[].username	string	User's normalized username
assignees[].discordId	string|null	User's Discord ID (for mentions)

Error Responses

Missing room parameter (400)

{
  "success": false,
  "error": "Missing required parameter: room",
  "usage": {
    "required": { "room": "Room name (e.g., 'PO Room', 'BKN1-10B ฝั่งขวา')" },
    "optional": {
      "currentTime": "Override time in HH:MM format (defaults to Bangkok now)",
      "sprint": "Override sprint (defaults to current sprint)"
    }
  },
  "example": "/api/room/next-booking?room=PO%20Room"
}

Invalid time format (400)

{
  "success": false,
  "error": "Invalid time format. Please use HH:MM format (e.g., '14:45')."
}

Server error (500)

{
  "success": false,
  "error": "Internal server error while fetching room booking.",
  "details": "Error message"
}

---

Sync Endpoints

Trigger Manual Sync

Manually trigger Google Sheets synchronization.

POST /api/sync/trigger

Example Request

curl -X POST "https://optimistic-alligator-723.convex.site/api/sync/trigger"

Response

{
  "success": true,
  "message": "Sync initiated successfully",
  "timestamp": "2026-01-28T11:45:00.000Z"
}

---

Get Sync Status

Check the current synchronization status.

GET /api/sync/status

Example Request

curl "https://optimistic-alligator-723.convex.site/api/sync/status"

Response

{
  "success": true,
  "lastSyncTime": 1706434800000,
  "lastSyncTimeFormatted": "2026-01-28T04:45:00.000Z",
  "totalBookings": 150,
  "status": "success",
  "currentSprint": "Sprint 96"
}

---

Booking Slot Endpoints

Get Next Booking Slot

Get the next 30-minute booking slot with all bookings.

GET /api/next-booking-slot

Parameters

Parameter	Type	Required	Description
currentTime	string	Yes	Current time in HH:MM format
day	string	Yes	Thai day name (e.g., วันจันทร์)
sprint	string	Yes	Sprint identifier (e.g., Sprint 96)
room	string	No	Filter by room name

Example Request

curl "https://optimistic-alligator-723.convex.site/api/next-booking-slot?currentTime=14:45&day=วันพุธ&sprint=3"

Response

{
  "found": true,
  "nextSlotStart": "15:00",
  "nextSlotEnd": "15:30",
  "totalBookings": 2,
  "bookings": [...],
  "message": "Found 2 booking(s) for slot 15:00 - 15:30"
}

---

Available Rooms

Common room names in the system:

Room Name	Description
PO Room	Product Owner room
meeting M	Meeting room M
meeting 2	Meeting room 2
mocap M	Motion capture room M
mocap 2	Motion capture room 2
Lightgun M	Lightgun room M
Lightgun QA	Lightgun QA room
โต๊ะตัวเอง	Personal desk

---

Notes

• All times are in Asia/Bangkok timezone (UTC+7)
• Room names are case-insensitive
• URL encode room names with spaces (e.g., PO%20Room)
• Thai day names: วันจันทร์, วันอังคาร, วันพุธ, วันพฤหัสบดี, วันศุกร์