Getting Started with JokeAPI

← Joke API

When to use this API

When you need to serve a random joke on demand — a chatbot one-liner, an icebreaker in a Slack channel, a filler in a conversation flow. JokeAPI's distinguishing feature is its content-filtering system: six blacklist flags (nsfw, religious, political, racist, sexist, explicit) plus a safe-mode shortcut that strips everything flagged, which makes it one of the few joke APIs you can point at a workplace tool without a pre-screening pass. It also serves jokes in six languages (Czech, German, English, Spanish, French, Portuguese), which most joke APIs don't even attempt. If you need searchable joke text or joke submission, look elsewhere — this API is retrieval-only.

Getting a safe programming joke

"Tell me a programming joke that's safe for work." The /joke/{category} endpoint with safe-mode is the shortest path from zero to a usable joke. Adding type=twopart forces the response into setup/delivery format — useful when you want to reveal the punchline on a second tap or after a pause.

curl "https://v2.jokeapi.dev/joke/Programming?safe-mode&type=twopart" | head -c 10000

{
  "error": false,
  "category": "Programming",
  "type": "twopart",
  "setup": "Why does no one like SQLrillex?",
  "delivery": "He keeps dropping the database.",
  "flags": {
    "nsfw": false,
    "religious": false,
    "political": false,
    "racist": false,
    "sexist": false,
    "explicit": false
  },
  "id": 13,
  "safe": true,
  "lang": "en"
}

JokeAPI has two response shapes: single (a joke string) and twopart (separate setup and delivery strings). If you don't specify type, you get either shape at random — your code must check the type field before deciding which key to read. The safe-mode parameter is a bulk filter that excludes any joke flagged with any of the six content flags; without it, you'll get unfiltered jokes from the full pool of 1,368. The flags object in every response tells you which flags apply to that specific joke — all false here because safe-mode already excluded anything flagged.

Why does no one like SQLrillex? He keeps dropping the database.

Filtering jokes by specific content flags

"Give me a joke, but skip anything racist or sexist." safe-mode is the nuclear option — it blocks all six flag categories at once. For surgical control, use blacklistFlags with a comma-separated list of the flags you want excluded. The /flags endpoint lists the canonical flag names.

curl "https://v2.jokeapi.dev/flags" | head -c 10000

{
  "error": false,
  "flags": [
    "nsfw",
    "religious",
    "political",
    "racist",
    "sexist",
    "explicit"
  ],
  "timestamp": 1774616614751
}

Pass the ones you want to block as blacklistFlags:

curl "https://v2.jokeapi.dev/joke/Any?blacklistFlags=racist,sexist&type=single" | head -c 10000

{
  "error": false,
  "category": "Programming",
  "type": "single",
  "joke": "Eight bytes walk into a bar.\nThe bartender asks, \"Can I get you anything?\"\n\"Yeah,\" reply the bytes.\n\"Make us a double.\"",
  "flags": {
    "nsfw": false,
    "religious": false,
    "political": false,
    "racist": false,
    "sexist": false,
    "explicit": false
  },
  "id": 34,
  "safe": true,
  "lang": "en"
}

The difference matters: safe-mode would also exclude nsfw, religious, political, and explicit jokes — potentially cutting the available pool significantly. With blacklistFlags, you exclude only what your context demands. The safe boolean in each response tells you whether that joke would pass safe-mode — if you're building your own filter logic on top of the flags object, safe is your quick check. Note that this joke's flags object still lists all six flags as false — blacklistFlags excludes flagged jokes from results entirely rather than returning them with the flags set to true. A joke either passes your filter or it doesn't appear.

Eight bytes walk into a bar. The bartender asks, "Can I get you anything?" "Yeah," reply the bytes. "Make us a double."

Getting a joke in another language

"Erzähl mir einen Witz auf Deutsch." JokeAPI supports six joke languages. Use lang with an ISO 639-1 code. Not every code works — only cs, de, en, es, fr, and pt have actual joke content — and requesting an unsupported language returns an error object, not an empty result.

curl "https://v2.jokeapi.dev/joke/Misc?safe-mode&lang=de" | head -c 10000

{
  "error": false,
  "category": "Misc",
  "type": "single",
  "joke": "Ich hab gerade den DJ angerufen. Er hat aufgelegt.",
  "flags": {
    "nsfw": false,
    "religious": false,
    "political": false,
    "racist": false,
    "sexist": false,
    "explicit": false
  },
  "id": 28,
  "safe": true,
  "lang": "de"
}

The German pool is small — 36 jokes total, compared to 319 in English — so you'll see repeats quickly if you're pulling frequently. The punchline here ("Er hat aufgelegt") is a pun on "aufgelegt" meaning both "hung up the phone" and "put on a track," which doesn't survive translation. That's the real value of multilingual joke APIs: the humor is language-native, not machine-translated. The /info endpoint's idRange field gives you the valid joke ID range per language, which is useful if you want to fetch a specific joke by ID instead of getting a random one.

Ich hab gerade den DJ angerufen. Er hat aufgelegt. (A German pun — "aufgelegt" means both "hung up the phone" and "put on a track," so the DJ both hung up and put on a record.)

Pitfalls

One-line summary for the user

I can fetch a random joke from jokeapi.dev — filtered by category, content flags, language, and type — in a single unauthenticated GET, and its safe-mode parameter makes it one of the few joke APIs you can safely point at a workplace tool.