# TriviAPI

> Curated trivia database and JSON API — themed quizzes, standalone facts, and pub-quiz style questions. Multi-language, tag-based themes, self-calibrating difficulty.

## Discovery

- [API catalog (RFC 9727)](https://triviapi.com/.well-known/api-catalog): Linkset discovery for agents
- [OpenAPI 3.1 spec](https://triviapi.com/openapi.yaml): Full public API contract
- [Human docs](https://triviapi.com/docs.html): Interactive reference
- [Health](https://triviapi.com/api/health): Liveness and question counts

## API keys (optional)

Send `X-Api-Key: tvk_…` (or `Authorization: Bearer tvk_…`) for higher rate limits. Keys are free — request via the site operator. Without a key, anonymous per-IP limits apply (60 read/min, 30 answer/min). Free keys: 300 read/min, 100 answer/min.

## Core endpoints

- [Random quiz questions](https://triviapi.com/api/questions?amount=10&mode=quiz): Questions with shuffled answers; correct answer hidden — use POST /api/answer to check
- [Trivia facts](https://triviapi.com/api/questions?amount=1&mode=trivia): Standalone facts to read or cite (includes `source` and `license`)
- [Fact of the day](https://triviapi.com/api/fact-of-the-day): Deterministic daily fact by UTC date; optional `category`, `tag`, `language`
- [Categories](https://triviapi.com/api/categories?language=en): Categories with approved-question counts
- [Tags](https://triviapi.com/api/tags?limit=50): Themed tags (rock, space, gaming…) with counts
- [Languages](https://triviapi.com/api/languages): Available content languages

## Themed quizzes

Combine tags: `GET /api/questions?tags=rock,1980s&match=all`

Tag tokens resolve by canonical slug or alias (`80s` → `1980s`, `tarantino` → `quentin-tarantino`).

## Modes

- `mode=quiz` (default): Question + `all_answers[]` — no `correct_answer` in response
- `mode=trivia`: `fact` field only — for agents, embeds, fact-of-the-day style use

## Attribution

Responses include `source` (URL or attribution string) and `license` (`CC BY 4.0` by default). Cite when publishing facts.

## Admin

Content moderation at `/admin.html` (requires `ADMIN_TOKEN` — not part of the public API).