> ## Documentation Index
> Fetch the complete documentation index at: https://docs.framesports.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authenticate, scope, and call the Framesports v1 API.

The Framesports API exposes read access to the same domain model used by the
product: **accounts**, **fixtures**, **games**, and **events**. It is used by
a small number of integration partners (e.g. broadcast-graphics tooling).

<Note>
  New integrations should prefer the `/api/v1/fixtures` endpoints over
  `/api/v1/games`. A fixture is the whole match — both sides, both rosters,
  all stats — in one payload. The games endpoints return one side at a time
  and are kept only for backwards compatibility.
</Note>

<Note>
  If you're building on the API and hit something that isn't covered here, email
  `support@framesports.ai` before reverse-engineering private endpoints.
</Note>

## Base URL

```
https://app.framesports.ai
```

All endpoints live under `/api/v1/`.

## Authentication

Every endpoint (except `POST /api/v1/auth` and `POST /api/v1/users`) requires a
bearer token:

```http theme={null}
Authorization: Bearer <token>
```

A token acts as the person who made it, with their access, for every request.

### Get a token

1. Sign in to Framesports and open [API tokens](https://2.framesports.ai/settings/my/api_tokens).
2. Choose **Create token**.
3. Give the token a name, choose the club it is for and choose when it expires.
4. Choose **Create token**, then copy the token. It is shown only once.

The same page shows each club's **Account ID** for the `Account-Id` header, and
lists your tokens with when each was last used. To stop a token, open its **⋯**
menu and choose **Delete token**. It stops working on its next request.

A token made for an AI assistant on **Settings → Third-Party AI** does not work
on this API.

If you can't see **API tokens** in your Settings menu, use the link in step 1. The
page works for everyone.

## Account scoping

Most endpoints are scoped to a single account (the multi-tenant unit — a club
or governing body). The account is selected in this priority order:

1. The `Account-Id` header on the request (prefix ID, e.g. `acct_Ex4mpLeAcc0unt1d567890`).
2. The club the token was made for.
3. The account stored in the user's session (for browser-originated calls).
4. The user's newest / fallback account.

<Warning>
  The server reads `Account-Id`, **not** `X-Account-Id`. If you send the
  `X-` prefixed version, it's silently ignored and the request falls back to
  rule 2 or later, which may not be the account you intended.
</Warning>

Error responses when the header is present but invalid:

| Situation | Status |
| - | - |
| Account does not exist | `404` |
| Account exists but user cannot access it | `403` |

## IDs

Object IDs are always **prefix IDs** — opaque strings with a type-specific prefix:

| Type | Prefix | Example |
| - | - | - |
| Account | `acct_` | `acct_Ex4mpLeAcc0unt1d567890` |
| Fixture | `fxt_` | `fxt_Ex4mpLeF1xtur31d34567890` |
| Game | `game_` | `game_Ex4mpLeG4m31d4567890abc` |
| Event | `evnt_` | `evnt_Ex4mpLe3v3nt1d4567890ab` |
| Team | `team_` | `team_Ex4mpLeTe4m1d4567890abc` |
| Player | `pl_` | `pl_Ex4mpLePL4y3r1d4567890abc` |
| PGI (player game involvement) | `pgi_` | `pgi_Ex4mpLePG1nv0Lv3m3nt4aa` |

Raw integer IDs are not accepted — always pass the prefix ID.

## Player identity

Within a fixture, each roster row (`players[]`) carries two identifiers.
They look similar but serve different purposes:

| Field | Scope | When to use it |
| - | - | - |
| `id` (`pgi_…`) | This row in this fixture | Referencing a specific teamsheet entry. |
| `player_id` | Stable across all fixtures | Aggregating the same person's stats across games. **This is the identity key.** |
| `name` | Display only | Showing to humans. |

<Warning>
  Don't key on `name`. The same name can appear multiple times in one lineup —
  most commonly `"Name Withheld"`, but also ordinary name collisions (two
  "John Smith"s in the same club). Rows that look identical by name are
  distinct people when `player_id` differs.
</Warning>

## Pagination

List endpoints use [Pagy](https://ddnexus.github.io/pagy/) with JSON:API-style
links. Pass `page` and `per_page` as query parameters:

```json theme={null}
{
  "links": {
    "first": "/api/v1/games/.../events?page[page]=1",
    "last":  "/api/v1/games/.../events?page[page]=9",
    "prev":  null,
    "next":  "/api/v1/games/.../events?page[page]=2"
  },
  "data": [ /* ... */ ]
}
```

## Errors

Errors are returned with an appropriate HTTP status and (usually) a JSON body
of the form `{ "error": "..." }`. Unauthenticated responses (`401`) currently
return an empty body with `content-type: text/html`. Treat any `401` as
"token missing, deleted, expired or not valid for this API", whatever the body.

## Versioning

`/api/v1/` is stable. Fields may be **added** without notice; fields will not
be **removed** or change meaning without a new major version. Any field whose
object includes `"deprecated": true` is scheduled for removal — migrate off it.

## Quick start

```bash theme={null}
# List fixtures for an account (preferred)
curl https://app.framesports.ai/api/v1/fixtures \
  -H "Authorization: Bearer $FRAMESPORTS_TOKEN" \
  -H "Account-Id: acct_Ex4mpLeAcc0unt1d567890"

# Search by team / competition / fixture name
curl "https://app.framesports.ai/api/v1/fixtures?query=wests" \
  -H "Authorization: Bearer $FRAMESPORTS_TOKEN" \
  -H "Account-Id: acct_Ex4mpLeAcc0unt1d567890"

# Get a single fixture: both sides, both rosters, all team + player stats
curl https://app.framesports.ai/api/v1/fixtures/fxt_Ex4mpLeF1xtur31d34567890 \
  -H "Authorization: Bearer $FRAMESPORTS_TOKEN" \
  -H "Account-Id: acct_Ex4mpLeAcc0unt1d567890"

# Page through events across both sides of a fixture
curl "https://app.framesports.ai/api/v1/fixtures/fxt_.../events?page=1&per_page=50" \
  -H "Authorization: Bearer $FRAMESPORTS_TOKEN" \
  -H "Account-Id: acct_Ex4mpLeAcc0unt1d567890"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.