Public API

Read your organisation's results, standings, fixtures, teams and players from your own website or app. Everything is read-only, scoped to your organisation, and authenticated with an API key you create yourself.

What you can build

The API exists so your league data can live on your own site without anyone copying scores by hand. Common uses are a results table on a club homepage, a live ladder, a fixtures list for the coming weekend, or a season summary per team.

The API is read-only. Nothing you do through it can change scores, fixtures or player records — scoring stays in the scoring apps.

Create an API key

Go to Settings → Integrations and click Create key. Give it a name that says where it will be used — "Club website" or "Season ladder widget" — so you can tell keys apart later when you need to revoke one.

Creating a key needs the Manage integrations permission. That is a deliberately higher bar than editing the organisation, because a key sends your data off the platform. Anyone who can edit the organisation can still see the key list and revoke keys — taking access away is never the risky direction.

The key is shown once

Scored stores only a hash of it, so it cannot be shown again and cannot be recovered. Copy it somewhere safe when you create it. If you lose it, revoke the key and create another — that is the intended path, not a failure.

Your first request

Send the key in an X-Api-Key header. Every endpoint lives under the same base URL:

curl https://api.scored.app/v1/results \
  -H "X-Api-Key: scored_your_key_here"

A successful response looks like this:

{
  "success": true,
  "message": "Results retrieved successfully",
  "data": {
    "results": [ /* ... */ ],
    "pagination": { "page": 1, "totalPages": 3, "total": 58 }
  }
}

You never send an organisation identifier. The organisation is taken from the key itself, and any organisation id you try to pass is ignored — a key can only ever read the data of the organisation that created it.

Identifiers are UIDs

Everything the API returns and accepts is identified by a UID — a stable value like 858bf080-5413-11f0-b70c-0ab4d4ca3065 — never an internal database number. So a team is a teamUID, a league is a leagueUID, a fixture is a fixtureUID.

Filters take the same UIDs. Passing a number where a UID belongs returns 404, as does a UID belonging to another organisation — the API does not distinguish between "does not exist" and "not yours", deliberately.

The one number you will see is sportId on a league, alongside the sport's name. That is a fixed public code for the sport itself (1 cricket, 2 netball, 3 volleyball, 4 football, 5 basketball), not a record id, and it is safe to switch on.

Using it from a browser

The API accepts requests from any origin, so a page on your own domain can call it directly with fetch. Bear in mind that anything in front-end JavaScript is visible to visitors — if the data is public on your site anyway, that is fine; if it is not, call the API from your server instead and pass the result through.

const response = await fetch("https://api.scored.app/v1/results", {
  headers: { "X-Api-Key": "scored_your_key_here" },
});
const { data } = await response.json();

Next

Getting Started
Public API