Skip to main content
GET
Get detailed spaces

Authorizations

Authorization
string
header
required

Access token issued by POST /sessions and associated with a valid server-side session.

Query Parameters

company_id
string<uuid>
required

Company UUID. Must equal the authenticated session company when that session has a company assigned; the equality check is skipped for sessions without one.

school_id
string<uuid>

School UUID. Must be assigned to the authenticated session. Omit to use the operation's documented company/session scope.

view
enum<string>

Omit for paginated rows or aggregation selected with group_by.

Available options:
trend,
projection,
periods
period
string

Required for rows and aggregates; not accepted in the other views.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$
room_id
string<uuid>

Optional for rows/projection; required for trend; rejected for aggregates and periods.

room_ids
string<uuid>[]

Optional for rows, aggregates and projection. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

school_ids
string<uuid>[]

Periods view only; each ID must be assigned to the session. Defaults to all assigned schools. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

only_active
boolean
default:false

Periods view only: include only active schools. Accepts true/1 and false/0, case-insensitive.

period_from
string

Trend/projection only: optional first monthly period. Omit both bounds or provide both within the available horizon.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$
period_to
string

Trend/projection only: optional last monthly period; must not precede period_from. Omit both bounds or provide both within the available horizon.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$
fields
enum<string>[]

Select response properties. Unknown names return 400. Rows and trend use SpacesRow fields; projection uses SpacesProjection fields. Invalid fields for the selected view return 400. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

Available options:
available_spaces,
capacity,
closed_spaces,
enrolled,
is_over_enrolled,
occupancy_rate,
occupied_spaces,
open_spaces,
period,
room_id,
room_name,
school_id,
school_name,
unavailable_spaces
sort_by
string

Rows: room_name, available_spaces, open_spaces, occupied_spaces or occupancy_rate with _asc/_desc. Aggregates: sum_available_spaces, sum_open_spaces, sum_occupied_spaces, sum_closed_spaces, sum_unavailable_spaces, capacity or occupancy_rate with _asc/_desc. Other views reject sort_by. Defaults: room_name_asc for rows; sum_open_spaces_desc for aggregates.

group_by
enum<string>

Select an aggregate representation; metrics must also be supplied.

Available options:
room_id,
room_name,
school_id,
school_name
metrics
enum<string>[]

Metrics to calculate; required with group_by and invalid without it. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

Available options:
sum_available_spaces,
sum_open_spaces,
sum_occupied_spaces,
sum_closed_spaces,
sum_unavailable_spaces,
capacity,
occupancy_rate
limit
integer
default:50

Aggregate result limit. Defaults to 50 and clamps values above 200 to 200. If provided, must be positive.

Required range: x >= 1
page
integer
default:1

One-based page number. Rows only; other representations reject pagination parameters.

Required range: x >= 1
per_page
integer
default:100

Items per page; values greater than 200 are clamped to 200. Rows only; other representations reject pagination parameters.

Required range: x >= 1

Response

Successful response.

A sparse row containing only the selected fields. Default fields: school_id, school_name, room_id, room_name, period, capacity, occupied_spaces, available_spaces, open_spaces, closed_spaces, unavailable_spaces, occupancy_rate.

school_id
string

School id.

school_name
string
room_id
string

Room id.

room_name
string
period
string
Pattern: ^\d{4}-(0[1-9]|1[0-2])$
capacity
integer
occupied_spaces
integer
available_spaces
integer
open_spaces
integer
closed_spaces
integer
unavailable_spaces
integer
occupancy_rate
number

Occupied spaces divided by capacity; ratio, not a percentage. Zero when capacity is zero.

is_over_enrolled
boolean