This is the contract the backend and frontend implement. Any change must update both sides in the same PR, and the root CLAUDE.md in the repo.

All endpoints except login need Authorization: Bearer <jwt>. Dates are YYYY-MM-DD in the office's time zone.

Every error returns the same shape:

{ "code": "SPACING_VIOLATION", "message": "A neighbouring desk is already booked for 2026-10-02." }

See Domain Rules for all error codes.

Request:

{ "username": "alice", "password": "..." }

Responses:

• 200 with { "token": "<jwt>", "username": "alice", "displayName": "Alice Anders" }
• 401 INVALID_CREDENTIALS

Every other /api/** call without a valid token returns 401 UNAUTHORIZED.

Lists floors.

[{ "id": 1, "name": "Floor 3", "rows": 8, "cols": 12, "neighbourMode": "ORTHOGONAL" }]

Returns the whole grid for one date, plus the current version of each desk.

{
  "floorId": 1,
  "date": "2026-10-02",
  "rows": 8,
  "cols": 12,
  "neighbourMode": "ORTHOGONAL",
  "cells": [
    { "id": 101, "row": 0, "col": 0, "type": "DESK", "label": "3-A1",
      "status": "BOOKED", "bookedBy": "Alice Anders", "bookedByUsername": "alice",
      "bookingId": 555, "seq": 1042 },
    { "id": 107, "row": 0, "col": 6, "type": "WALKWAY", "label": null,
      "status": null, "bookedBy": null, "bookedByUsername": null, "bookingId": null, "seq": null }
  ]
}

row and col are 0-based. bookingId is included only on your own booking, so you can cancel it. The snapshot takes a fixed two queries, whatever the floor size.

Request:

{ "deskId": 101, "date": "2026-10-02" }

When several rules fail, the code returned is DESK_TAKEN, then ALREADY_BOOKED_TODAY, then SPACING_VIOLATION.

Returns your bookings from today onward.

See Real-Time Updates.