API Reference

The Ballr Club Website API is organized around REST. It uses predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Premium clubs can call the API a few times a day from their own website’s server, cache the response, and display fixtures, results, stats, and feed posts to visitors. Do not call the API from browser JavaScript or on every page view — that would expose your key and exhaust your daily quota.

Base URL

https://demo.ballr.club/api/v1/club

Just getting started?

Generate an API key in Club Admin → Website API (Super Admins), then make a single combined request and store the JSON on your site.

REQUESTGET

curl https://ballr.club/api/v1/club \
  -H "Authorization: Bearer ballr_..."

Authentication

Authenticate requests by including your club API key in the Authorization header:

HEADER

Authorization: Bearer ballr_...

You can also pass ?api_key=ballr_... as a query parameter for quick testing, but the Bearer header is preferred for production.

Keys are shown once at generation and stored as a hash. Regenerating a key immediately invalidates the previous one. Manage keys in Club Settings → Website API.

Rate limits

Each club may make 24 requests per day. A combined call counts as one request. Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers, and a meta.rate_limit object in the JSON body.

When the quota is exceeded, the API returns 429 with guidance to cache responses and refresh a few times daily.

Errors

Ballr uses conventional HTTP response codes to indicate success or failure.

Code	Meaning
`200`	Success
`304`	Not modified (valid `If-None-Match` / ETag)
`401`	Missing or invalid API key
`403`	Club is not on Ballr Plus
`429`	Daily rate limit exceeded

Caching & ETags

Responses include an ETag. Send it back as If-None-Match on later requests to receive 304 Not Modified when nothing has changed. Conditional requests still count toward your daily quota.

Ballr also caches API sections server-side for a short period. Your website should still store responses and refresh periodically (for example hourly, within the daily limit).

GET

Retrieve club data

https://demo.ballr.club/api/v1/club

Returns club info plus fixtures, results, stats, and feed in a single payload. Use include to select sections.

Parameters

Param	Type	Description
`include`	string	Comma-separated: `fixtures,results,stats,feed`. Defaults to all.
`fixture_limit` / `result_limit` / `feed_limit`	integer	Per-section limits (max 50).
`team_id`, `season`, `type`	mixed	Same filters as the individual endpoints below.

Returns

A data object with info and any included sections, plus meta (club slug, timestamp, rate limit).

REQUESTGET

curl https://ballr.club/api/v1/club \
  -H "Authorization: Bearer ballr_..."

RESPONSE

{
  "data": {
    "info": {
      "club": {
        "id": 1,
        "name": "Newtown Forest FC",
        "slug": "newtown-forest",
        "logo_url": "https://ballr.club/storage/clubs/logos/crest.png",
        "primary_color": "#2d2e7a",
        "profile_url": "https://ballr.club/newtown-forest"
      },
      "next_match": { "opponent_name": "Rivals FC", "match_date": "2026-07-18" },
      "last_result": { "outcome": "Win", "club_score": 2, "opponent_score": 1 }
    },
    "fixtures": [ /* ... */ ],
    "results": [ /* ... */ ],
    "stats": { "players": [ /* ... */ ] },
    "feed": [ /* ... */ ]
  },
  "meta": {
    "club": "newtown-forest",
    "generated_at": "2026-07-11T13:00:00+00:00",
    "rate_limit": { "limit": 24, "remaining": 23 }
  }
}

GET

Retrieve club info

https://demo.ballr.club/api/v1/club/info

Club branding, contact details, social links, and convenience objects for next_match and last_result — ideal for a homepage widget.

REQUESTGET

curl https://ballr.club/api/v1/club/info \
  -H "Authorization: Bearer ballr_..."

GET

List fixtures

https://demo.ballr.club/api/v1/club/fixtures

Upcoming matches (excluding cancelled practice sessions), soonest first.

Parameters

Param	Type	Description
`team_id`	integer	Optional team filter.
`limit`	integer	Default 10, max 50.

REQUESTGET

curl "https://ballr.club/api/v1/club/fixtures?limit=10" \
  -H "Authorization: Bearer ballr_..."

GET

List results

https://demo.ballr.club/api/v1/club/results

Past matches with scores and outcome (Win / Draw / Loss). Published match reports include title, body, and report URL. Each match includes opponent_badge_url when a badge has been uploaded for that opponent.

Parameters

Param	Type	Description
`team_id`	integer	Optional team filter.
`limit`	integer	Default 10, max 50.

REQUESTGET

curl "https://ballr.club/api/v1/club/results?limit=10" \
  -H "Authorization: Bearer ballr_..."

GET

List player stats

https://demo.ballr.club/api/v1/club/stats

Aggregated competitive-match stats for active players: goals, assists, cards, Star Player awards, and appearances.

Parameters

Param	Type	Description
`season`	string	Season name as shown on the club profile (e.g. `2026/27`). Defaults to the club’s current season if omitted or not found.
`all_seasons`	boolean	Pass `1` to aggregate across all seasons.
`team_id`	integer	Optional team filter.

REQUESTGET

curl "https://ballr.club/api/v1/club/stats?season=2026%2F27" \
  -H "Authorization: Bearer ballr_..."

GET

List feed posts

https://demo.ballr.club/api/v1/club/feed

Club feed posts with absolute image URLs (url, large_url, thumb_url) and a post_url back to Ballr.

Parameters

Param	Type	Description
`limit`	integer	Default 20, max 50.
`type`	string	`manual`, `match_fixture`, or `match_report`.

REQUESTGET

curl "https://ballr.club/api/v1/club/feed?limit=20" \
  -H "Authorization: Bearer ballr_..."