API reference

Generated from the OpenAPI 3.1 document at /api/v1/openapi.json. Paths below are relative to https://sportsmgnt.com/api/v1.

Version 1.0.0 · Download the OpenAPI document · Developers

REST API of the SportsMgnt demonstration platform built by WeldonPC. All data is sample data for the fictional Kestrel Basin Parks & Recreation District and resets nightly. Responses use the envelope {"data": ..., "meta": {...}}; errors use {"error": {"code", "message", "fields"}}.

catalog

Public activity catalog (no token needed)

GET `/activities`

Search activity sessions (same filters as the /activities page)

No token needed

Parameters: GET /activities
Name	In	Type	Required	Description
`q`	query	string	No	Keyword (title, description or code)
`category`	query	string	No	Category slug, e.g. aquatics
`age`	query	integer	No	Participant age
`grade`	query	string	No	School grade K or 1-12
`location`	query	string	No	Location code, e.g. L-HPCC
`near_location`	query	string	No	Location code to measure distance from
`distance`	query	integer	No	Kilometres from near_location: 1, 3, 5 or 10
`day[]`	query	array of string (mon, tue, wed, thu, fri, sat, sun)	No	Days of week (mon..sun); repeat day[]
`time`	query	string	No	morning, afternoon or evening
`from`	query	string	No	Earliest start time HH:MM
`to`	query	string	No	Latest end time HH:MM
`language`	query	string	No	en, es or bilingual
`adaptive`	query	integer	No	1 = adaptive programs only
`open`	query	integer	No	1 = sessions with open seats only
`season`	query	string	No	Season code
`page`	query	integer	No	Page number
`per_page`	query	integer	No	Rows per page (max 100)

Responses

200 Paginated sessions
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/activities' \
  -H 'Accept: application/json'

GET `/activities/{code}`

One activity (program code like AQ-L2, or a session code) with its sessions

No token needed

Parameters: GET /activities/{code}
Name	In	Type	Required	Description
`code`	path	string	Yes

Responses

200 Activity
404 Not found
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/activities/AQ-L2' \
  -H 'Accept: application/json'

GET `/locations`

Locations of the fictional district with grid coordinates

No token needed

Responses

200 Locations
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/locations' \
  -H 'Accept: application/json'

core

Health and token information

GET `/health`

Service health

No token needed

Responses

200 OK
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/health' \
  -H 'Accept: application/json'

GET `/me/token`

Describe the calling token

Token required

Responses

200 The token's user, scopes and expiry
401 Missing, invalid, revoked or expired token
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/me/token' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

facilities

Facility inventory and availability (public)

GET `/facilities`

List facilities

Public. Filters match the web catalog.

No token needed

Parameters: GET /facilities
Name	In	Type	Required	Description
`type`	query	string	No	Facility type
`location`	query	integer	No	Location id
`capacity`	query	integer	No	Minimum capacity
`amenity`	query	string	No	Amenity key
`accessible`	query	string	No	Accessibility feature key
`bookable`	query	string	No	1 = bookable online only
`q`	query	string	No	Search text
`page`	query	integer	No	Page number
`per_page`	query	integer	No	Items per page (max 100)

Responses

200 OK
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/facilities' \
  -H 'Accept: application/json'

GET `/facilities/{slug}`

One facility

No token needed

Parameters: GET /facilities/{slug}
Name	In	Type	Required	Description
`slug`	path	string	Yes

Responses

200 OK
404 Unknown facility

Example request

curl 'https://sportsmgnt.com/api/v1/facilities/riverbend-shelter-1' \
  -H 'Accept: application/json'

GET `/facilities/{slug}/availability`

Free and busy times per day

Agency-local times (meta.timezone). Busy blocks carry a state but never who booked them.

No token needed

Parameters: GET /facilities/{slug}/availability
Name	In	Type	Required	Description
`slug`	path	string	Yes
`from`	query	string	No	First date (YYYY-MM-DD, default today)
`to`	query	string	No	Last date (default from + 6 days; at most 31 days)

Responses

200 OK
404 Unknown facility
422 Invalid date range

Example request

curl 'https://sportsmgnt.com/api/v1/facilities/riverbend-shelter-1/availability' \
  -H 'Accept: application/json'

household

The signed-in household (personal access token with household:read)

GET `/me/calendar`

Calendar items between two dates (agency time; default the next 30 days; scope household:read)

Token required

Parameters: GET /me/calendar
Name	In	Type	Required	Description
`from`	query	string (date)	No
`to`	query	string (date)	No

Responses

200 Calendar items
422 Invalid range
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/me/calendar' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

GET `/me/cart`

The household's open cart with seat-hold expiry times (scope household:read)

Token required

Responses

200 Cart
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/me/cart' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

GET `/me/enrollments`

Enrolments of the household, newest first (scope household:read)

Token required

Parameters: GET /me/enrollments
Name	In	Type	Required
`status`	query	string	No
`page`	query	integer	No
`per_page`	query	integer	No

Responses

200 Enrolments
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/me/enrollments' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

GET `/me/household`

The token user's active household (scope household:read)

Token required

Responses

200 Household
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/me/household' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

GET `/me/members`

Household members (scope household:read; no medical data)

Token required

Responses

200 Members
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/me/members' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

reservations

Facility reservation requests (token)

GET `/reservations`

Your household's reservations

Token scope household:read.

Token required

Parameters: GET /reservations
Name	In	Type	Required	Description
`page`	query	integer	No	Page number
`per_page`	query	integer	No	Items per page (max 100)

Responses

200 OK
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission

Example request

curl 'https://sportsmgnt.com/api/v1/reservations' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

POST `/reservations`

Request a reservation

Token scope reservations:write. Creates a request only: no payment is taken and nothing is confirmed here. The same validation as the web form applies (booking windows, opening hours, capacity, slot locks). Pay, sign and upload paperwork from the reservation page.

Token required

Request body

Request body: POST /reservations
Property	Type	Required	Description
`facility`	string	Yes	Facility slug
`household`	string	No	H-number; defaults to the token user's active household
`mode`	string (once, weekly, dates)	No
`date`	string (date)	No
`days`	array of integer	No	ISO weekdays for mode=weekly
`until`	string (date)	No
`dates`	array of string (date)	No
`start`	string	Yes	Agency-local time, 15-minute steps
`end`	string	Yes
`purpose`	string (private, nonprofit, school, commercial)	No
`attendees`	integer	Yes
`title`	string	No
`organisation`	string	No
`notes`	string	No
`on_conflict`	string (block, drop)	No
`agreement`	object	No	Optional: sign the rental agreement now

Responses

201 Request created
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
409 A requested time is already taken (program, booking, league game or blackout)
422 Validation failed
429 Too many requests; see Retry-After

Example request

curl -X POST 'https://sportsmgnt.com/api/v1/reservations' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"facility":"string","household":"string","mode":"once","date":"2026-10-12","days":[1],"until":"2026-10-12","dates":["2026-10-12"],"start":"10:00","end":"13:00","purpose":"private","attendees":1,"title":"string","organisation":"string","notes":"string","on_conflict":"block","agreement":{"signer_name":"string","consent":true}}'

GET `/reservations/{id}`

One reservation

Token scope household:read.

Token required

Parameters: GET /reservations/{id}
Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

200 OK
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
404 Not found or not yours

Example request

curl 'https://sportsmgnt.com/api/v1/reservations/1' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

staff

Staff back office: rosters, attendance and reports. Requires a staff token with the matching scope; the token user's role and location scope apply, and an instructor-only user sees only the sessions they teach.

POST `/staff/attendance`

Record attendance for a meeting

Scope staff:attendance. The token user needs attendance.mark at the meeting's location (instructor-only users: their own sessions).

Token required

Request body

Request body: POST /staff/attendance
Property	Type	Required	Description
`meeting_id`	integer	Yes
`records`	array of object	Yes

Responses

200 Saved
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
404 No such meeting
422 Invalid records
429 Too many requests; see Retry-After

Example request

curl -X POST 'https://sportsmgnt.com/api/v1/staff/attendance' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"meeting_id":1,"records":[{"enrollment_id":1,"status":"present"}]}'

GET `/staff/reports/{key}`

Run a library report

Scope staff:reports. Rows are limited to the token user's location scope. Keys: enrolment, revenue_cost_center, daily_cash, transmittals, refunds_status, waitlists, facility_utilization, attendance_pct, instructor_hours, demographics, fee_assistance, inventory, donations_fund, passes, balances_aging, audit_summary.

Token required

Parameters: GET /staff/reports/{key}
Name	In	Type	Required
`key`	path	string	Yes
`from`	query	string (date)	No
`to`	query	string (date)	No
`location`	query	integer	No
`season`	query	integer	No

Responses

200 Report rows (sample data)
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
404 Unknown report
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/staff/reports/key' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

GET `/staff/rosters/{session}`

Roster of a session

Scope staff:rosters. The token user needs rosters.view at the session's location; an instructor-only user must be assigned to the session.

Token required

Parameters: GET /staff/rosters/{session}
Name	In	Type	Required	Description
`session`	path	string	Yes	Session code (KB-F26-1012) or numeric id

Responses

200 Roster
401 Missing, invalid, revoked or expired token
403 The token lacks a scope, or the user lacks a permission
404 No such session
429 Too many requests; see Retry-After

Example request

curl 'https://sportsmgnt.com/api/v1/staff/rosters/KB-F26-1001' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Schemas

`Activity` object

Activity
Property	Type	Required
`code`	string	Yes
`type`	string	Yes
`title`	string	Yes
`description`	string	Yes
`category`	string	Yes
`ages`	object	Yes
`grades`	object	No
`residents_only`	boolean	No
`language`	string	No
`adaptive`	boolean	No
`required_waivers`	array of string	No
`required_documents`	array of string	No
`accessibility_notes`	string	No
`sessions`	array of ActivitySession	Yes

`ActivitySession` object

ActivitySession
Property	Type	Required
`code`	string	Yes
`program_code`	string	Yes
`title`	string	Yes
`type`	string (class, camp, overnight_camp, league, child_care, dropin, event)	Yes
`category`	string	No
`season`	string	No
`location`	object	Yes
`facility`	string \| null	No
`start_date`	string (date)	Yes
`end_date`	string (date)	Yes
`days`	array of string	Yes
`start_time`	string	Yes
`end_time`	string	Yes
`ages`	object	No
`language`	string	No
`adaptive`	boolean	No
`capacity`	integer	Yes
`seats_left`	integer	Yes
`waitlisted`	integer	Yes
`resident_price_cents`	integer	Yes
`registration`	object	Yes
`url`	string	No

`AttendanceRequest` object

AttendanceRequest
Property	Type	Required	Description
`meeting_id`	integer	Yes
`records`	array of object	Yes

`AttendanceResult` object

AttendanceResult
Property	Type	Required	Description
`data`	object	No
`meta`	Meta	No

`AvailabilityDay` object

AvailabilityDay
Property	Type	Required
`date`	string (date)	Yes
`open`	boolean	Yes
`opens_at`	string	Yes
`closes_at`	string	Yes
`free`	array of object	Yes
`busy`	array of object	Yes

`CalendarItem` object

CalendarItem
Property	Type	Required
`type`	string	Yes
`title`	string	Yes
`person`	string \| null	No
`person_id`	integer \| null	No
`starts_at`	string (date-time)	Yes
`ends_at`	string (date-time)	Yes
`location`	string	Yes
`facility`	string \| null	No
`notes`	string \| null	No

`Cart` object

Cart
Property	Type	Required	Description
`items`	array of object	Yes
`total_cents`	integer	Yes

`Enrollment` object

Enrollment
Property	Type	Required
`id`	integer	Yes
`session`	string	Yes
`title`	string	Yes
`person_id`	integer	Yes
`status`	string (pending_review, enrolled, waitlisted, offered, cancelled, transferred, completed)	Yes
`waitlist_position`	integer \| null	No
`enrolled_at`	string \| null (date-time)	No
`offer_expires_at`	string \| null (date-time)	No
`start_date`	string (date)	No
`end_date`	string (date)	No

`Error` object

Error
Property	Type	Required	Description
`error`	object	Yes

`Facility` object

Facility
Property	Type	Required
`slug`	string	Yes
`name`	string	Yes
`type`	string	Yes
`location`	object	Yes
`capacity`	integer	Yes
`amenities`	array of string	No
`accessible_features`	array of string	No
`bookable_online`	boolean	Yes
`approval_steps`	integer	Yes
`instant_booking`	boolean	Yes
`insurance_required`	boolean	Yes
`deposit_cents`	integer	Yes
`min_notice_days`	integer	Yes
`max_advance_days`	integer	Yes
`cutoff_days`	integer	Yes
`opens_at`	string	Yes
`closes_at`	string	Yes
`url`	string	Yes

`FacilityDetail`

`Household` object

Household
Property	Type	Required
`public_id`	string	Yes
`name`	string	Yes
`kind`	string	No
`residency`	string (resident, nonresident)	Yes
`zip`	string \| null	No
`status`	string	No
`income_status`	string	No
`income_verified_until`	string \| null (date)	No
`role`	string \| null (primary, secondary, )	Yes
`members`	integer	Yes
`balance_cents`	integer	Yes
`credit_cents`	integer	Yes

`Location` object

Location
Property	Type	Required
`code`	string	Yes
`name`	string	Yes
`address`	string	Yes
`phone`	string \| null	No
`x_km`	number	Yes
`y_km`	number	Yes
`point_of_sale`	boolean	No
`hours`	object	No

`Member` object

Member
Property	Type	Required
`id`	integer	Yes
`first_name`	string	Yes
`last_name`	string	Yes
`age`	integer \| null	No
`relation`	string	Yes
`guardian_role`	string	Yes
`school_grade`	string \| null	No
`has_allergy`	boolean	No

`Meta` object

Meta
Property	Type	Required
`total`	integer	No
`page`	integer	No
`per_page`	integer	No

`ReportResult` object

ReportResult
Property	Type	Required	Description
`data`	object	No
`meta`	object	No

`Reservation` object

Reservation
Property	Type	Required
`id`	string	Yes
`status`	string (draft, submitted, in_review, approved, awaiting_payment, confirmed, denied, cancelled)	Yes
`status_label`	string	No
`facility`	object	Yes
`household`	string	Yes
`purpose`	string (private, nonprofit, school, commercial)	Yes
`attendees`	integer	Yes
`title`	string \| null	No
`current_step`	integer	Yes
`approval_steps`	integer	Yes
`total_cents`	integer	Yes
`deposit_cents`	integer	Yes
`amount_due_cents`	integer	Yes
`insurance_status`	string (not_required, required, submitted, approved, rejected)	Yes
`checkpoints`	object	Yes
`dates`	array of object	Yes
`url`	string	Yes

`ReservationRequest` object

ReservationRequest
Property	Type	Required	Description
`facility`	string	Yes	Facility slug
`household`	string	No	H-number; defaults to the token user's active household
`mode`	string (once, weekly, dates)	No
`date`	string (date)	No
`days`	array of integer	No	ISO weekdays for mode=weekly
`until`	string (date)	No
`dates`	array of string (date)	No
`start`	string	Yes	Agency-local time, 15-minute steps
`end`	string	Yes
`purpose`	string (private, nonprofit, school, commercial)	No
`attendees`	integer	Yes
`title`	string	No
`organisation`	string	No
`notes`	string	No
`on_conflict`	string (block, drop)	No
`agreement`	object	No	Optional: sign the rental agreement now

`Roster` object

Roster
Property	Type	Required	Description
`data`	object	No
`meta`	Meta	No

`RosterParticipant` object

RosterParticipant
Property	Type	Required	Description
`enrollment_id`	integer	Yes
`person_id`	integer	Yes
`first_name`	string	Yes
`last_name`	string	Yes
`age`	integer \| null	No
`household`	string	No
`allergy`	boolean	Yes
`allergy_note`	string \| null	No	Only for users with medical.view at the session's location; each read is audited.
`guardian_phone`	string \| null	No
`emergency_contacts`	array of object	No
`authorized_pickups`	array of string	No
`checkin_code`	string	Yes	Code on the participant's QR pass, for check-in.

API reference

catalog

GET /activities

Responses

GET /activities/{code}

Responses

GET /locations

Responses

core

GET /health

Responses

GET /me/token

Responses

facilities

GET /facilities

Responses

GET /facilities/{slug}

Responses

GET /facilities/{slug}/availability

Responses

household

GET /me/calendar

Responses

GET /me/cart

Responses

GET /me/enrollments

Responses

GET /me/household

Responses

GET /me/members

Responses

reservations

GET /reservations

Responses

POST /reservations

Request body

Responses

GET /reservations/{id}

Responses

staff

POST /staff/attendance

Request body

Responses

GET /staff/reports/{key}

Responses

GET /staff/rosters/{session}

Responses

Schemas

Activity object

ActivitySession object

AttendanceRequest object

AttendanceResult object

AvailabilityDay object

CalendarItem object

Cart object

Enrollment object

Error object

Facility object

FacilityDetail

Household object

Location object

Member object

Meta object

ReportResult object

Reservation object

ReservationRequest object

Roster object

RosterParticipant object

GET `/activities`

GET `/activities/{code}`

GET `/locations`

GET `/health`

GET `/me/token`

GET `/facilities`

GET `/facilities/{slug}`

GET `/facilities/{slug}/availability`

GET `/me/calendar`

GET `/me/cart`

GET `/me/enrollments`

GET `/me/household`

GET `/me/members`

GET `/reservations`

POST `/reservations`

GET `/reservations/{id}`

POST `/staff/attendance`

GET `/staff/reports/{key}`

GET `/staff/rosters/{session}`

`Activity` object

`ActivitySession` object

`AttendanceRequest` object

`AttendanceResult` object

`AvailabilityDay` object

`CalendarItem` object

`Cart` object

`Enrollment` object

`Error` object

`Facility` object

`FacilityDetail`

`Household` object

`Location` object

`Member` object

`Meta` object

`ReportResult` object

`Reservation` object

`ReservationRequest` object

`Roster` object

`RosterParticipant` object