Chuck Norris Database API Tutorial — Chuck Norris Database API

When to use this API

When you need to serve a Chuck Norris joke in response to a user's lighthearted request — "tell me a joke", "give me something funny about coding", "I need a conversation starter". The database is hand-curated, not generated, so the jokes have actual comedic structure. It covers 16 thematic categories, from dev to science to political, which matters when context calls for a specific flavor. This is purely a Chuck Norris joke delivery API — it does not cover other comedians, joke formats, or humor styles beyond the Chuck Norris format.

Getting a random Chuck Norris joke

"Tell me a Chuck Norris joke." The /jokes/random endpoint returns a single joke in one unauthenticated call — no key, no token, no preamble. To narrow by theme, add ?category=dev (or any of the 16 categories from /jokes/categories); without a filter, the call draws from the full general pool.

curl "https://api.chucknorris.io/jokes/random" | head -c 10000

{
  "categories": [],
  "created_at": "2020-01-05 13:42:24.40636",
  "icon_url": "https://api.chucknorris.io/img/avatar/chuck-norris.png",
  "id": "ogHqV2c2Q_iV4O3NeoW3Ew",
  "updated_at": "2020-01-05 13:42:24.40636",
  "url": "https://api.chucknorris.io/jokes/ogHqV2c2Q_iV4O3NeoW3Ew",
  "value": "The fastest way to a man's heart is Chuck Norris' fist."
}

The categories: [] is not a bug — it means this joke lives in the general uncategorized pool, which is larger than any single named category. Only a subset of jokes carry an explicit category tag. The url field is a shareable permalink: https://api.chucknorris.io/jokes/ogHqV2c2Q_iV4O3NeoW3Ew links directly to this specific joke, useful if the user wants to save or forward it.

Here's one: "The fastest way to a man's heart is Chuck Norris' fist." (chucknorris.io)

Searching for jokes on a specific topic

"Find Chuck Norris jokes about computers." Use /jokes/search?query= for full-text search across all joke text — useful when the concept you want spans multiple categories or has no dedicated category at all.

curl "https://api.chucknorris.io/jokes/search?query=computer" | head -c 10000

{
  "total": 26,
  "result": [
    {
      "categories": [],
      "created_at": "2020-01-05 13:42:19.104863",
      "id": "y-b7g8trr96pfmopdplf4g",
      "url": "https://api.chucknorris.io/jokes/y-b7g8trr96pfmopdplf4g",
      "value": "Chuck Norris doesn't use a computer because a computer does everything slower than Chuck Norris."
    }
    // ... 25 more results
  ]
}

The total field arrives before you parse any individual joke — use it to tell the user "there are 26 jokes about X" or to select one at random by index rather than always defaulting to result[0]. The search endpoint returns all matches at once with no pagination, so prefer specific keywords over broad single-character queries.

I found 26 Chuck Norris jokes about computers. Here's one: "Chuck Norris doesn't use a computer because a computer does everything slower than Chuck Norris."

Discovering available joke categories

"What kinds of Chuck Norris jokes are there?" Call /jokes/categories before recommending a filtered joke — it returns all 16 category strings in a single lightweight response.

curl "https://api.chucknorris.io/jokes/categories" | head -c 10000

["animal", "career", "celebrity", "dev", "explicit", "fashion", "food", "history", "money", "movie", "music", "political", "religion", "science", "sport", "travel"]

dev is a first-class category for programmer-humor jokes, which is more targeted than a keyword search for "programming" that would match partial or tangential results. explicit is also in the list — if building for a family-friendly context, filter to a specific safe category with ?category=science rather than relying on unfiltered random results.

The Chuck Norris joke database has 16 categories: animal, career, celebrity, dev (programmer humor), explicit, fashion, food, history, money, movie, music, political, religion, science, sport, and travel. Which flavor would you like?

Pitfalls

Every created_at and updated_at timestamp in the database is 2020-01-05 — the entire dataset was bulk-imported on that date. The timestamps are meaningless for sorting or finding "recent" jokes; they reflect database ingest time, not joke authorship or recency.
The search endpoint returns all matches in a single response with no pagination. Broad queries return large payloads; use specific keywords rather than short common words.
The explicit category is listed alongside the others and is reachable via both /jokes/random?category=explicit and keyword search. Filter explicitly if your context requires family-safe output.

One-line summary for the user

I can serve random or category-filtered Chuck Norris jokes, or search the hand-curated chucknorris.io database by keyword — no auth required, but the dataset is frozen at its 2020 import state with no new additions since.