API Reference

Full endpoint documentation for the Staty REST API.

Base URL: https://api.staty.io/api/v1

Authentication

All requests require an Authorization header:


Authorization: Bearer sk_live_abc123...

Generate keys from Settings → API Keys in the Admin dashboard . See Developer API: Getting Started for full instructions.

Available Scopes

Scope	Access
`read:leagues`	Read seasons, tournaments, divisions
`read:teams`	Read teams and rosters
`read:players`	Read player profiles and stats
`read:games`	Read game schedule and scores
`read:registrations`	Read registration submissions
`write:registrations`	Submit registrations on behalf of users
`read:payments`	Read payment status
`admin`	Full read/write access

Response Envelope

All responses use this format:


{
  "success": true,
  "data": [ ... ],
  "count": 5
}

Query Parameter: `?include=`

By default, list and detail endpoints return only the immediate fields of the requested resource. Reference fields (e.g. league, paymentProduct, homeTeam) are returned as bare ObjectId strings. To get them populated as nested objects, opt in with ?include=.

Breaking change in v1.1: several endpoints that previously auto-populated reference fields (e.g. GET /divisions/:id always returned league and layout as objects) now return them as ObjectId strings unless you ask for them with ?include=. See the changelog for the full list.

Grammar

?include= accepts a comma-separated list. Each token supports four forms:

Token	Effect
`a`	Populate the `a` reference.
`a,b`	Populate `a` and `b`.
`a.b`	Populate `a`, then populate `a.b` on the result (nested).
`a.b.c`	Three-level nesting.
`a(x,y)`	Populate `a` and return only fields `x` and `y` on the populated doc.
`a.b(x,y)`	Nested populate with field selection on the leaf.

Examples

Single populate:


GET /api/v1/divisions/div_123?include=league

Multiple flat populates:


GET /api/v1/divisions/div_123?include=league,layout

Nested populate (populate homeTeam, and on each homeTeam populate its players):


GET /api/v1/games/game_abc?include=homeTeam.players,awayTeam.players

Field selection (return only name and _id on the populated user):


GET /api/v1/payments?include=user(name,email)

Combination — populate requestedDivision, then populate paymentProduct on it, returning only name and price:


GET /api/v1/registrationTeams/rt_xyz?include=requestedDivision.paymentProduct(name,price)

Rules

Unknown roots are silently ignored. Passing ?include=evil won’t error; the field just doesn’t appear.
Each endpoint allow-lists root paths. If a root isn’t allowed on that endpoint, the token is ignored. Allowed roots are listed in each endpoint’s docs.
Same-root tokens merge. ?include=players.team,players.organization,players.league produces a single populate on players with three sub-populates — equivalent to populating each one separately and merging.
_id is always included in populated docs. You don’t need to add it to (...) selects.

Feature Endpoints

Feature	Category	Endpoint
Season Management	League	`/api/v1/leagues`
Tournament Brackets	League	`/api/v1/tournaments`
Divisions & Standings	League	`/api/v1/divisions`
Team Registration	Registration	`/api/v1/registrations`
Digital Waivers	Registration	`/api/v1/waivers`
Player Profiles	Players	`/api/v1/players`
Game Scheduling	Scheduling	`/api/v1/games`
Venue Management	Scheduling	`/api/v1/locations`
Payments	Payments	`/api/v1/payments`
Game Statistics	Analytics	`/api/v1/stats`
Audit Logs	Developer	`/api/v1/auditLogs`

Rate Limits

Plan	Requests/minute
Free	60
Pro	300
Enterprise	Custom

When exceeded: 429 Too Many Requests. Check the Retry-After header.

See Errors & Rate Limits for full error code reference.