BYTETOOLS

JokeAPI

Free JokeAPI with no key: programming, pun and miscellaneous jokes with category filters, blacklist flags and safe mode for family-friendly output. Tested.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-20

What is the JokeAPI?

JokeAPI is a free, key-free jokes API offering programming, pun, spooky and miscellaneous jokes, with category filtering, content blacklist flags and a safe mode that guarantees family-friendly output.

JokeAPI is the most configurable of the free joke APIs. Beyond categories, it exposes a blacklist system letting you exclude jokes flagged as nsfw, religious, political, racist, sexist or explicit — individually or all at once.

The `safe-mode` flag is the important one for any public-facing product. Joke APIs without content filtering will eventually serve something you did not want on your site, and this is the only free one that takes that seriously.

Quick facts

Base URL
https://v2.jokeapi.dev
Authentication
No API key required.
Rate limit
120 requests per minute per IP.
Pricing
Free and open source.
CORS
Enabled — callable directly from browser JavaScript
Official docs
Read the docs

How to use the JokeAPI

Every request below was executed against the live API on 2026-08-20, and the response shown is the real body it returned — not an illustration.

1. Fetch a programming joke

GET https://v2.jokeapi.dev/joke/Programming?type=single&safe-mode

curl
curl 'https://v2.jokeapi.dev/joke/Programming?type=single&safe-mode'
JavaScript (fetch)
const res = await fetch("https://v2.jokeapi.dev/joke/Programming?type=single&safe-mode");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);
Python (requests)
import requests

res = requests.get("https://v2.jokeapi.dev/joke/Programming?type=single&safe-mode", timeout=20)
res.raise_for_status()
print(res.json())
Response — HTTP 200
{
  "error": false,
  "category": "Programming",
  "type": "single",
  "joke": "// This line doesn't actually do anything, but the code stops working when I delete it.",
  "flags": {
    "nsfw": false,
    "religious": false,
    "political": false,
    "racist": false,
    "sexist": false,
    "explicit": false
  },
  "id": 12,
  "safe": true,
  "lang": "en"
}

Parameters

ParameterTypeRequiredDescription
joke/<category>pathRequiredAny, Programming, Misc, Dark, Pun, Spooky, Christmas. joke/Programming
typestringOptionalsingle or twopart. single
safe-modeflagOptionalGuarantee family-friendly output. safe-mode
blacklistFlagsstringOptionalComma-separated flags to exclude. nsfw,racist
amountintegerOptionalNumber of jokes, up to 10. 5
langstringOptionalen, de, es, fr, pt, cs. en

Response fields

errorboolean
False on success — check this first.
categorystring
Which category the joke came from.
typestring
single or twopart.
jokestring
The joke, on single-type responses.
setup / deliverystring
The two halves, on twopart responses.
flagsobject
Content flags — nsfw, religious, political, racist, sexist, explicit.
safeboolean
Whether the joke passed safe-mode checks.

What you can build with the JokeAPI

  • Add a safe joke command to a Discord or Slack bot
  • Show programming humour on a developer site
  • Build a joke app with content filtering for a general audience
  • Practise handling APIs with two different response shapes

Common errors and how to fix them

Two different response shapes

single has `joke`; twopart has `setup` and `delivery`.

Fix: Branch on the `type` field, or force one with type=single.

Unwanted content

Default output is unfiltered.

Fix: Always add safe-mode for public-facing use — this is the API's main advantage, so use it.

429

Exceeded 120 requests per minute.

Fix: Cache, or request several jokes at once with `amount`.

JokeAPI — frequently asked questions

Is JokeAPI free?

Yes, completely free and open source with no API key, limited to 120 requests per minute.

How do I keep jokes family-friendly?

Add the safe-mode flag, which guarantees filtered output. You can also exclude specific content types with blacklistFlags. This filtering is JokeAPI's main advantage over simpler joke APIs.

Why do responses have different shapes?

Single jokes use a `joke` field; two-part jokes use `setup` and `delivery`. Branch on `type`, or force one format with type=single.

Which languages are supported?

English, German, Spanish, French, Portuguese and Czech, selected with the `lang` parameter.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

Random Number Generator

Generate random numbers in any range with cryptographically secure randomness. Multiple numbers, no-repeat mode, sorting, plus dice and coin presets.

JokeAPI is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-20; always check the official documentation before relying on this API in production, as terms and limits can change.