API Documentation

The Disc Database is served as a read-only JSON:API — discs, manufacturers, plastics, flight numbers, disc classes, and variants, all connected through standard relationships.

Getting Started

Base URL

text
https://api.thediscdatabase.com/api/v1

All endpoints live under this base URL and are versioned at v1.

Authentication

Every request needs a bearer token and the JSON:API content type. Tokens are scoped to the resources they can read and are issued personally while the platform is in early access — request one here.

bash
curl "https://api.thediscdatabase.com/api/v1/discs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Rate limits

Tokens are limited to 60 requests per minute and 1,000 per hour. Current usage is reported on every response via the X-RateLimit-Limit and X-RateLimit-Remaining headers.

Read-only, by design

The API only serves data — every endpoint is a GET. Changes to the database go through the contributor review workflow, never through the API.

Querying

Standard JSON:API query parameters are supported everywhere:

  • filter[...] — exact-match filters (e.g. filter[slug], filter[manufacturer_slug])
  • sort — e.g. sort=name or sort=-pdgaApprovedOn
  • page[number] / page[size] — page-based pagination
  • include — side-load related resources in one request
  • fields[...] — sparse fieldsets
bash
curl "https://api.thediscdatabase.com/api/v1/discs?filter[manufacturer_slug]=innova&sort=-pdgaApprovedOn&include=flight-characteristic&page[size]=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"