RoomLoop Back to sign in
API Reference v1

RoomLoop REST API

A clean, predictable JSON API. All endpoints are HTTPS-only and require a bearer token. Rate limits apply per token.

Base URL
https://api.roomloop.dev
Auth
Bearer + Google SSO
Webhooks
Signed HMAC-SHA256
POST
/v1/auth/google
Exchange Google OAuth ID token for a RoomLoop session.
Authentication
POST
/v1/auth/logout
Revoke the current session.
Authentication
GET
/v1/facilities
List all facilities. Supports ?type, ?building, ?status filters.
Facilities
GET
/v1/facilities/:id
Retrieve a single facility with amenities and capacity.
Facilities
GET
/v1/facilities/:id/availability
Slot-by-slot availability for a date. Pass ?date=YYYY-MM-DD.
Facilities
PATCH
/v1/facilities/:id
Update facility metadata. Admin only.
Facilities
POST
/v1/reservations
Create a reservation. Runs the rules engine.
Reservations
GET
/v1/reservations
List reservations. ?user_id, ?facility_id, ?from, ?to.
Reservations
PATCH
/v1/reservations/:id
Update purpose or status (confirm / cancel).
Reservations
DELETE
/v1/reservations/:id
Permanently delete a reservation. Admin only.
Reservations
GET
/v1/accounts
List teacher accounts. ?department, ?role.
Accounts
POST
/v1/accounts
Provision a single account.
Accounts
POST
/v1/accounts/bulk
CSV bulk upload. multipart/form-data with `file` field.
Accounts
GET
/v1/accounts/export
Download all teacher accounts as CSV.
Accounts
GET
/v1/reports/usage
Usage aggregates. ?from, ?to, ?facility_id, ?user_id.
Reports
GET
/v1/reports/export.csv
Stream a CSV export of reservations in a range.
Reports
GET
/v1/reports/export.xlsx
Stream an Excel export of reservations in a range.
Reports
POST
/v1/webhooks
Register a webhook for reservation.* and account.* events.
Webhooks
Example — create reservation
The booking endpoint returns the canonical resource with rules-engine outcome embedded.
POST /v1/reservations
Authorization: Bearer sk_live_•••••••••••••••
Content-Type: application/json

{
  "facility_id": "f1",
  "date": "2026-06-10",
  "start_slot": 2,
  "end_slot": 3,
  "purpose": "Grade 10 Chemistry — titration lab"
}

// 201 Created
{
  "id": "res_8f3e21",
  "status": "confirmed",
  "facility": { "id": "f1", "name": "STEM Lab Alpha" },
  "date": "2026-06-10",
  "slots": ["10:00–10:50", "11:00–11:50"],
  "created_at": "2026-06-08T09:14:00Z"
}
Errors
Standard HTTP status codes plus a structured body.
400validation_error
Body failed schema validation.
401unauthorized
Missing or expired bearer token.
403forbidden
Role lacks the required capability.
409slot_conflict
Rules engine R-03: another booking occupies the slot.
422rule_violation
Rules engine refused the request. Includes failing rule code.
429rate_limited
Per-token rate limit exceeded.