# OddsFinder API

> Canonical football data with full revision history.

Version 0.1.0. Base URL `https://api.example.com`. The base URL is a placeholder, and the recorded examples come from a synthetic test dataset (made-up names and sources).

When you write code against this API:

- Send `X-API-Key: <customer key>` or `Authorization: Bearer <user token>` with every `/v1` request.
- Timestamps are RFC 3339 in UTC with a `Z` suffix, in requests and responses; offsets are rejected.
- Exact decimals are strings, never JSON numbers; a missing value is `null` with a sibling status saying why.
- Lists return `items` and `page.next_cursor`; pass the cursor back as `cursor` with the same filters until it is `null`.
- Errors are Problem Details (`application/problem+json`) with a `type` of `urn:oddsfinder:problem:<slug>`; a `429` carries `Retry-After`. Quote `X-Request-Id` when reporting a problem.

## Reference

- [Full reference](llms-full.txt): conventions, every endpoint with its parameters, returned fields, errors and a recorded example, as Markdown
- [OpenAPI document](openapi.json): the canonical contract (OpenAPI 3.1.1)

## Conventions

- [Authentication](md/t-authentication.md)
- [Errors](md/t-errors.md)
- [Pagination](md/t-pagination.md)
- [Identifiers](md/t-identifiers.md)
- [Timestamps](md/t-timestamps.md)
- [Exact decimals](md/t-exact-decimals.md)
- [Missing values](md/t-missing-values.md)
- [Enumerated values can grow](md/t-enumerated-values-can-grow.md)
- [Time semantics](md/t-time-semantics.md)
- [Freshness delay and source references](md/t-freshness-delay-and-source-references.md)
- [Rate limit and allowances](md/t-rate-limit-and-allowances.md)
- [Match facts and source rights](md/t-match-facts-and-source-rights.md)
- [HEAD](md/t-head.md)
- [Request id](md/t-request-id.md)

## Competitions

- [The competition object](md/obj-Competition.md)
- [The competition detail object](md/obj-CompetitionDetail.md)
- [`GET /v1/competitions`](md/listCompetitions.md): List competitions
- [`GET /v1/competitions/{id}`](md/getCompetition.md): Get a competition

## Seasons

- [The season detail object](md/obj-SeasonDetail.md)
- [`GET /v1/seasons/{id}`](md/getSeason.md): Get a season

## Stages

- [The stage object](md/obj-Stage.md)
- [`GET /v1/stages/{id}`](md/getStage.md): Get a stage

## Clubs

- [The club object](md/obj-Club.md)
- [`GET /v1/clubs/{id}`](md/getClub.md): Get a club

## Teams

- [The team object](md/obj-Team.md)
- [`GET /v1/teams/{id}`](md/getTeam.md): Get a team

## Persons

- [The person object](md/obj-Person.md)
- [`GET /v1/persons`](md/listPersons.md): List persons by role
- [`GET /v1/persons/{id}`](md/getPerson.md): Get a person

## Venues

- [The venue object](md/obj-Venue.md)
- [`GET /v1/venues/{id}`](md/getVenue.md): Get a venue

## Fixtures

- [The fixture object](md/obj-Fixture.md)
- [`GET /v1/fixtures`](md/listFixtures.md): List fixtures in a competition and kickoff window
- [`GET /v1/fixtures/{id}`](md/getFixture.md): Get a fixture

## Match facts

- [The fixture lineups object](md/obj-FixtureLineups.md)
- [The fixture statistics object](md/obj-FixtureStatistics.md)
- [The fixture events object](md/obj-FixtureEvents.md)
- [The fixture sidelined object](md/obj-FixtureSidelined.md)
- [The fixture officials object](md/obj-FixtureOfficials.md)
- [The fixture conditions object](md/obj-FixtureConditions.md)
- [`GET /v1/fixtures/{id}/lineups`](md/getFixtureLineups.md): Get a fixture's lineups
- [`GET /v1/fixtures/{id}/statistics`](md/getFixtureStatistics.md): Get a fixture's statistics
- [`GET /v1/fixtures/{id}/events`](md/getFixtureEvents.md): Get a fixture's match events
- [`GET /v1/fixtures/{id}/sidelined`](md/getFixtureSidelined.md): Get a fixture's sidelined players
- [`GET /v1/fixtures/{id}/officials`](md/getFixtureOfficials.md): Get a fixture's officials
- [`GET /v1/fixtures/{id}/conditions`](md/getFixtureConditions.md): Get a fixture's conditions

## Results

- [The result object](md/obj-Result.md)
- [`GET /v1/results/{id}`](md/getResult.md): Get a result

## Account

- [The coverage item object](md/obj-CoverageItem.md)
- [The entitlements object](md/obj-Entitlements.md)
- [The usage object](md/obj-Usage.md)
- [`GET /v1/coverage`](md/getCoverage.md): Dataset coverage visible to the caller
- [`GET /v1/me/entitlements`](md/getMyEntitlements.md): Effective entitlements of the caller
- [`GET /v1/me/usage`](md/getMyUsage.md): Metered usage and quota of the caller's organization