Getting Started with the Chuck Norris Jokes API — Chuck Norris Jokes API

When to use this API

When a user asks for a Chuck Norris joke — random, themed, or matching a specific keyword. No auth. No key. The API is narrow by design: it covers exactly one comedian's fictional mythology and nothing else. For general-purpose humor (dad jokes, programming puns, multi-subject joke collections), JokeAPI or icanhazdadjoke are better fits. What this API offers beyond sheer randomness is 16 named categories — from dev to travel to science — plus full-text search across a curated set of several hundred jokes, which lets you tune the output for an audience without doing any client-side filtering.

Getting a random joke

"Tell me a Chuck Norris joke." The /jokes/random endpoint takes no required parameters and returns one joke object. The dev category is worth knowing about if you're in a coding-assistant context: it returns jokes that reference programming concepts, making them land better with technical users than a generic roundhouse-kick joke would.

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

{
  "categories": [],
  "created_at": "2020-01-05 13:42:23.880601",
  "icon_url": "https://api.chucknorris.io/img/avatar/chuck-norris.png",
  "id": "HTxN_A8gR42PcRlWZUJYSw",
  "updated_at": "2020-01-05 13:42:23.880601",
  "url": "https://api.chucknorris.io/jokes/HTxN_A8gR42PcRlWZUJYSw",
  "value": "Everything on Chuck Norris' properties are powered by a deus ex machina"
}

categories: [] is the norm, not a sign of missing data — the majority of jokes in the dataset are untagged. Only jokes explicitly classified belong to one of the 16 named categories. The id and url fields together give you a stable permalink for every joke, so you can link directly if you want. To narrow to a theme, add ?category=dev (or any other category name) to the URL; the categories field in the response will then confirm the filter as ["dev"].

Here's a Chuck Norris joke: "Everything on Chuck Norris' properties are powered by a deus ex machina."

Searching for jokes about a specific topic

"Do you have any Chuck Norris jokes about Mortal Kombat?" The /jokes/search endpoint takes a query parameter and returns all matching jokes along with a total count. Use specific multi-word queries — broad terms return hundreds of results.

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

{
  "total": 2,
  "result": [
    {
      "categories": [],
      "id": "v5bjnMaRTk2dW3lCGAfkVQ",
      "url": "https://api.chucknorris.io/jokes/v5bjnMaRTk2dW3lCGAfkVQ",
      "value": "Chuck Norris was secretly included for Mortal Kombat X. The developers then changed their minds and removed him because 1 hit from Chuck Norris = a fatality."
    }
    // ... 1 more result
  ]
}

The total field is the decision hinge: when it's 2, return both jokes (or pick the better one); when it's 593 (which happens with a single common word as the query), pick one from result at random and surface just that. The result array is the filtered set actually returned in the response, not the full total — if the total is large, the response only gives you a subset to work with.

I found 2 Chuck Norris jokes about Mortal Kombat. Here's the better one: "Chuck Norris was secretly included for Mortal Kombat X. The developers then changed their minds and removed him because 1 hit from Chuck Norris = a fatality."

Discovering available categories

"What themes of Chuck Norris jokes can you get?" Call /jokes/categories to get the complete list before choosing a category filter.

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"]

The list is stable across probes — 16 categories, unchanged. The explicit category is included here and counts as a valid filter for /jokes/random. When you call /jokes/random without any category parameter, explicit jokes can appear in the pool; the categories field on the returned joke will tell you whether the one you got is tagged ["explicit"]. Screen it before surfacing to users who didn't ask for adult content.

Chuck Norris jokes come in 16 themes: animal, career, celebrity, dev, explicit, fashion, food, history, money, movie, music, political, religion, science, sport, and travel. Which theme do you want?

Pitfalls

Explicit jokes are in the default random pool. Calling /jokes/random with no category filter can return jokes tagged ["explicit"]. Check the categories field on the returned joke, or call with a specific safe category like ?category=science or ?category=dev.
The dataset is frozen. Every joke in the DB has a created_at of 2020-01-05. The collection has not grown since then — don't expect recent cultural references or new material.
Short search queries are firehoses. Searching for a single common word returns hundreds of results. Use specific multi-word phrases, or combine with a category approach when the topic is broad.

One-line summary for the user

I can fetch a random Chuck Norris joke — filtered by any of 16 categories or matched by keyword — from chucknorris.io with no authentication required.