Create a room

Creates a physical or online room in your institution. Required: name and personCapacity. For physical rooms, personCapacity must be at least 1; for online rooms set isOnline: true and personCapacity: 0. Optionally link amenities (discover via GET /amenities) and a location in the same request. Scoped to your integration’s institution via Basic Auth credentials.

POST/rooms

Header parameters

Idempotency-Keystringrequired

Request body

requiredapplication/json

namestringrequired

Display name for the room, shown in the dashboard and when scheduling appointments (e.g. `Lecture Hall A`, `Seminar Room 3`).

max length 100

personCapacityintegerrequired

Maximum number of people the room holds. Required on create. Must be at least `1` for physical rooms (`isOnline: false` or omitted). Use `0` only when `isOnline` is `true`.

min 0 · max 1000

codestring

Optional short identifier for the room. When omitted or empty, a unique code is auto-generated from `name`.

max length 50

addressNotesstring

Optional free-text notes for finding or accessing the room (e.g. directions, door codes, wheelchair access).

max length 1000

amenityIdsstring[]

Optional IDs of equipment/amenities to link to the room (e.g. `Projector`, `Whiteboard`). Discover available amenities via GET /amenities. Amenities must belong to your institution.

locationIdstring | null

Optional ID of a location (campus/building) this room belongs to. Pass `null` to leave the room unassigned.

isOnlineboolean

Whether this is a virtual/online room rather than a physical space. When `true`, `personCapacity` may be `0` and `onlineLink` can hold the meeting URL.

onlineLinkstring | null

Meeting or video link for online rooms (e.g. Zoom or Teams URL). Only relevant when `isOnline` is `true`.

max length 2000

Responses

201Room created

dataRoomDetailrequired

Full room returned by GET /rooms/{id}, POST /rooms, and PATCH /rooms/{id}. Includes location, equipmentAndAmenities, courses, modules, and scheduledChanges (sorted by most recent startDate first).

Show properties

idstringrequired

namestringrequired

institutionIdstringrequired

personCapacityintegerrequired

addressNotesstringrequired

Additional address notes. Empty string when not set.

codestring | null

locationIdstring | null

statusstringrequired

Allowed:ACTIVEMAINTENANCEINACTIVE

isOnlinebooleanrequired

onlineLinkstring | null

locationLocationSummary | any

Show properties

One of:

LocationSummary

idstringrequired

namestringrequired

Display name for the location — the label shown in the dashboard when managing rooms and assigning them to a site (e.g. `Main Campus`, `North Building`, `Sleeping Pod Area`).

max length 100

addressstringrequired

Physical street or postal address of the location. Used in the dashboard for map display and geocoding — provide a real-world address, not the location name repeated (e.g. `123 University Ave, 10115 Berlin`).

max length 500

institutionIdstringrequired

any

any

equipmentAndAmenitiesAmenity[]required

Structured equipment and amenities linked to the room.

Show properties

Array of Amenity

idstringrequired

institutionIdstringrequired

namestringrequired

createdAtstring<date-time>required

updatedAtstring<date-time>required

colorstring | null

iconstring | null

coursesobject[]required

Show properties

Array of object

idstringrequired

roomIdstringrequired

courseIdstringrequired

courseobjectrequired

Show properties

idstringrequired

namestringrequired

codestring | null

colorinteger | null

iconstring | null

iconTypestring | null

layer_idstringrequired

modulesobject[]required

Show properties

Array of object

idstringrequired

roomIdstringrequired

moduleIdstringrequired

moduleobjectrequired

Show properties

idstringrequired

namestringrequired

codestring | null

scheduledChangesRoomScheduledChange[]required

All scheduled status windows for this room (past, active, and future), sorted by most recent startDate first.

Show properties

Array of RoomScheduledChange

idstringrequired

roomIdstringrequired

statusstringrequired

Allowed:ACTIVEMAINTENANCEINACTIVE

startDatestring<date-time>required

endDatestring<date-time> | null

reasonstring | null

createdAtstring<date-time>required

createdByobject | anyrequired

Show properties

One of:

object

idstringrequired

namestringrequired

any

any

metaResponseMetarequired

Show properties

requestIdstringrequired

timestampstring<date-time>required

versionstringrequired

Allowed:v4

400Bad Request

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

401Unauthorized

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

409Conflict

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

422Unprocessable Entity — validation or business rule error

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

429Too Many Requests

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

500Internal Server Error

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedrate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

Request

curl -X POST "https://fuxam.app/api/v4/rooms" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Lecture Hall A",
  "personCapacity": 120,
  "code": "LHA",
  "addressNotes": "",
  "amenityIds": [
    "string"
  ],
  "locationId": "loc_001",
  "isOnline": false,
  "onlineLink": null
}'

const response = await fetch("https://fuxam.app/api/v4/rooms", {
  method: "POST",
  headers: {
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "name": "Lecture Hall A",
  "personCapacity": 120,
  "code": "LHA",
  "addressNotes": "",
  "amenityIds": [
    "string"
  ],
  "locationId": "loc_001",
  "isOnline": false,
  "onlineLink": null
})
});

import requests

response = requests.post(
    "https://fuxam.app/api/v4/rooms",
    headers={
        "Idempotency-Key": "string",
        "Content-Type": "application/json"
    },
    json={
  "name": "Lecture Hall A",
  "personCapacity": 120,
  "code": "LHA",
  "addressNotes": "",
  "amenityIds": [
    "string"
  ],
  "locationId": "loc_001",
  "isOnline": False,
  "onlineLink": None
},
)

Response

{
  "data": {
    "id": "room_001",
    "name": "Lecture Hall A",
    "institutionId": "inst_123",
    "personCapacity": 120,
    "addressNotes": "",
    "code": "LHA",
    "locationId": "loc_001",
    "status": "ACTIVE",
    "isOnline": false,
    "onlineLink": null,
    "equipmentAndAmenities": [
      {
        "id": "amen_001",
        "institutionId": "inst_123",
        "name": "Projector",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-06-01T00:00:00.000Z",
        "color": "#0361fc",
        "icon": "projector"
      }
    ],
    "location": {
      "id": "loc_001",
      "name": "Main Campus",
      "address": "123 University Ave",
      "institutionId": "inst_123"
    },
    "courses": [
      {
        "id": "rc_001",
        "roomId": "room_001",
        "courseId": "course_001",
        "course": {
          "id": "course_001",
          "name": "Introduction to CS",
          "code": "CS101",
          "color": 5,
          "icon": "/illustrations/course-icon-library/book-worm.webp",
          "iconType": "image",
          "layer_id": "layer_001"
        }
      }
    ],
    "modules": [
      {
        "id": "rm_001",
        "roomId": "room_001",
        "moduleId": "cm_xyz789",
        "module": {
          "id": "cm_xyz789",
          "name": "Economics",
          "code": "ECO-101"
        }
      }
    ],
    "scheduledChanges": [
      {
        "id": "rss_001",
        "roomId": "room_001",
        "status": "MAINTENANCE",
        "startDate": "2026-07-01T00:00:00.000Z",
        "endDate": "2026-07-05T23:59:00.000Z",
        "reason": "Annual HVAC maintenance",
        "createdAt": "2026-06-15T10:00:00.000Z",
        "createdBy": {
          "id": "user_001",
          "name": "Jane Doe"
        }
      }
    ]
  },
  "meta": {
    "requestId": "req_1234567890_abc",
    "timestamp": "2026-06-02T07:00:00.000Z",
    "version": "v4"
  }
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}