git:20260705.acb5571 to git:20260705.a28c4ce

17 added, 17 removed. Audit A to A.

---

name: Fun Content APIs

- description: Use when a task needs light entertainment content from a live API — "build a quiz/trivia game", "random dog picture", "cat fact", "advice of the day", "random fun fact" — for a demo, bot, party feature, or filler content slot. Open Trivia DB is the quiz default (its session-token mechanics are documented here); catfact.ninja, random.dog, Advice Slip, and Useless Facts cover the rest, all keyless. Do NOT use for placeholder users/products/images in a prototype — use test-placeholder-data instead; do NOT use for dictionary or encyclopedia lookups — use language-reference instead; if the request is a vague "I need live data", route through public-data-api-picker.

+ description: Use when a task needs light entertainment content from a live API - "build a quiz/trivia game", "random dog picture", "cat fact", "advice of the day", "random fun fact" - for a demo, bot, party feature, or filler content slot. Open Trivia DB is the quiz default (its session-token mechanics are documented here); catfact.ninja, random.dog, Advice Slip, and Useless Facts cover the rest, all keyless. Do NOT use for placeholder users/products/images in a prototype - use test-placeholder-data instead; do NOT use for dictionary or encyclopedia lookups - use language-reference instead; if the request is a vague "I need live data", route through public-data-api-picker.

---

# Fun Content APIs

Pull trivia, animal images, and one-liner facts from verified keyless endpoints. The mistakes this prevents: shipping a quiz that repeats questions because Open Trivia DB's token mechanics were skipped, printing raw HTML entities in questions, and citing one of this category's chronically-dead quote APIs from training memory.

## Ranked APIs

- 1. **Open Trivia DB** (opentdb.com) — DEFAULT for quiz/trivia: 4,000+ questions, categories, difficulties. No key, but has session-token and encoding mechanics (below) that naive integrations get wrong.

- 2. **catfact.ninja** — random cat facts. **random.dog** — random dog images (the better-known Dog CEO API at dog.ceo is returning HTTP 520s, verified — see Do NOT).

- 3. **Advice Slip** (api.adviceslip.com) and **Useless Facts** (uselessfacts.jsph.pl) — one-liner advice and fun facts.

+ 1. **Open Trivia DB** (opentdb.com) - DEFAULT for quiz/trivia: 4,000+ questions, categories, difficulties. No key, but has session-token and encoding mechanics (below) that naive integrations get wrong.

+ 2. **catfact.ninja** - random cat facts. **random.dog** - random dog images (the better-known Dog CEO API at dog.ceo is returning HTTP 520s, verified - see Do NOT).

+ 3. **Advice Slip** (api.adviceslip.com) and **Useless Facts** (uselessfacts.jsph.pl) - one-liner advice and fun facts.

## Procedure

- 1. **Trivia beyond one throwaway call → get a session token first.** The token makes the API track served questions so users never see repeats. Rate limit: **1 request per IP per 5 seconds** — batch up to 50 questions per call instead of calling per-question.

- 2. **Decode the questions.** Default responses are HTML-encoded (`"`, `'`). Either decode entities client-side or request `&encode=url3986` and URL-decode — do one of them, or apostrophes render as garbage.

+ 1. **Trivia beyond one throwaway call → get a session token first.** The token makes the API track served questions so users never see repeats. Rate limit: **1 request per IP per 5 seconds** - batch up to 50 questions per call instead of calling per-question.

+ 2. **Decode the questions.** Default responses are HTML-encoded (`"`, `'`). Either decode entities client-side or request `&encode=url3986` and URL-decode - do one of them, or apostrophes render as garbage.

3. **Check `response_code` on every trivia call.** `0` ok; `1` not enough questions for the filters (loosen category/difficulty); `3`/`4` token missing or exhausted (request/reset token); `5` rate-limited (wait 5s).

- 4. **Shuffle answers.** `correct_answer` and `incorrect_answers` arrive separated — merge and shuffle before display or the correct answer's position leaks.

- 5. **Animal images: fetch the JSON, then use the URL inside it.** For random.dog, filter for image extensions — it also serves `.mp4`/`.webm`.

+ 4. **Shuffle answers.** `correct_answer` and `incorrect_answers` arrive separated - merge and shuffle before display or the correct answer's position leaks.

+ 5. **Animal images: fetch the JSON, then use the URL inside it.** For random.dog, filter for image extensions - it also serves `.mp4`/`.webm`.

- Ask the user only if missing — trivia: question count (default: 10), category (default: any), difficulty (default: any).

+ Ask the user only if missing - trivia: question count (default: 10), category (default: any), difficulty (default: any).

## URL templates + real response shapes

**Trivia session + questions:**

```

https://opentdb.com/api_token.php?command=request ← once per user session

https://opentdb.com/api.php?amount=10&type=multiple&token={token}

https://opentdb.com/api.php?amount=10&category=9&difficulty=easy&token={token} ← 9 = General Knowledge

https://opentdb.com/api_category.php ← id → name list

https://opentdb.com/api_token.php?command=reset&token={token} ← on response_code 4

```

```json

{"response_code":0,"results":[{"type":"multiple","difficulty":"easy",

"category":"Entertainment: Musicals & Theatres",

"question":"In Shakespeare's play Julius Caesar, Caesar's last words were...",

"correct_answer":"Et tu, Brute? ",

"incorrect_answers":["Iacta alea est!","Vidi, vini, vici.","Aegri somnia vana."]}]}

```

Tokens expire after 6 hours of inactivity. Max `amount=50` per call.

**One-liners and animals:**

```

https://catfact.ninja/fact → {"fact":"...","length":94}

https://random.dog/woof.json → {"url":"https://random.dog/….jpg","fileSizeBytes":170059}

https://api.adviceslip.com/advice → {"slip":{"id":89,"advice":"Don't be afraid to ask questions."}}

- https://api.adviceslip.com/advice/search/{q} → {"slips":[...]} — 404s (JSON body) on no match

+ https://api.adviceslip.com/advice/search/{q} → {"slips":[...]} - 404s (JSON body) on no match

https://uselessfacts.jsph.pl/api/v2/facts/random → {"text":"...","source":"...","permalink":"..."}

```

- Advice Slip caches responses for ~2 seconds — identical repeat calls return the same slip; don't build "another one!" loops tighter than that.

+ Advice Slip caches responses for ~2 seconds - identical repeat calls return the same slip; don't build "another one!" loops tighter than that.

## Deliverable

For a quiz: working token lifecycle (request → use → reset on code 4), entity-decoded questions, shuffled answers, `response_code` handled. For content slots: the fetched item plus the URL used, with image extensions filtered where the API mixes media types.

- ## Do NOT use — reach for X instead

+ ## Do NOT use - reach for X instead

- - **Dog CEO (dog.ceo)** — returning HTTP 520 on all endpoints, verified; random.dog replaces it.

- - **quotes.rest, favqs unauthenticated, zenquotes at volume, kanye.rest and friends** — this category's quote APIs are chronically down or throttled to uselessness; Advice Slip and Useless Facts are the verified survivors. Probe before adding any other.

- - **Placeholder people/products/images for a prototype** — test-placeholder-data (Picsum for generic images; this skill's animals are content, not layout filler).

- - **Word definitions, encyclopedia facts** — language-reference.

- - **Anything load-bearing.** These are volunteer-run free services — fine for demos and bots, wrong as a paid product's sole content source.

+ - **Dog CEO (dog.ceo)** - returning HTTP 520 on all endpoints, verified; random.dog replaces it.

+ - **quotes.rest, favqs unauthenticated, zenquotes at volume, kanye.rest and friends** - this category's quote APIs are chronically down or throttled to uselessness; Advice Slip and Useless Facts are the verified survivors. Probe before adding any other.

+ - **Placeholder people/products/images for a prototype** - test-placeholder-data (Picsum for generic images; this skill's animals are content, not layout filler).

+ - **Word definitions, encyclopedia facts** - language-reference.

+ - **Anything load-bearing.** These are volunteer-run free services - fine for demos and bots, wrong as a paid product's sole content source.

## Quality bar

- Multi-question trivia sessions use a token; zero repeated questions.

- No raw `"` or `'` ever reaches the user.

- Answer order is shuffled; `response_code` paths are handled, not assumed zero.

Sourced and liveness-verified from the public-apis project (MIT).