About

Humor delivery is a combinatorial problem. With thousands of jokes across 6 categories and multiple structural formats (single-line, two-part setup/punchline), selecting an appropriate joke requires filtering by topic, sensitivity flags, and format. This generator queries the JokeAPI v2 endpoint in real time, applying category and blacklist parameters server-side before delivery. A local fallback dataset of 50 jokes activates when the network is unavailable. Favorites persist in LocalStorage across sessions.

The tool addresses a practical problem: sourcing contextually appropriate humor for presentations, icebreakers, or content creation. Sending an off-color joke in a professional setting carries real social risk. The blacklist filter system (religious, political, racist, sexist, explicit, nsfw) maps directly to the API's blacklistFlags parameter, ensuring output matches your audience constraints. Note: joke quality is crowd-sourced and unmoderated beyond flag categories. Results approximate "safe" humor but edge cases exist.

Formulas

The joke retrieval follows a parameterized API query construction pattern. The endpoint URL is assembled from user-selected options:

URL = base + categories + flags + type

Where base = https://v2.jokeapi.dev/joke/, categories is a comma-separated list from the set {Programming, Misc, Pun, Spooky, Christmas, Dark}, flags is the blacklistFlags query parameter, and type constrains format to single or twopart.

The offline fallback uses a deterministic pseudo-random index:

index = floor(random() × N)

Where N is the cardinality of the filtered fallback set. Favorites are stored as a JSON array in LocalStorage with deduplication by joke id. History maintains a FIFO queue capped at 20 entries, where the oldest entry is evicted when the limit is exceeded.

{

source = API if navigator.onLine = TRUEsource = fallback[] if navigator.onLine = FALSE

Reference Data

Category	Description	Typical Format	Avg. Length (words)	Audience
Programming	Software, code, developer culture	Two-part	18	Tech professionals
Misc	General humor, everyday situations	Mixed	22	Universal
Pun	Wordplay and double meanings	Single	12	Universal
Spooky	Horror-themed, dark-adjacent	Two-part	16	Halloween / casual
Christmas	Holiday-themed humor	Two-part	15	Seasonal events
Dark	Morbid, controversial edge humor	Mixed	20	Adults only
Blacklist Flags (Sensitivity Filters)
nsfw	Not safe for work content	-	-	Filter out for professional use
religious	References to religion	-	-	Filter for diverse audiences
political	Political commentary	-	-	Filter for neutral settings
racist	Racial stereotypes	-	-	Always recommended to filter
sexist	Gender-based humor	-	-	Filter for inclusive settings
explicit	Profanity and graphic content	-	-	Filter for all-ages audiences
Joke Formats
single	One-liner joke, complete in one string	Single	8 - 25	Quick delivery
twopart	Setup + punchline delivery	Two-part	12 - 35	Traditional format
API Response Codes
200	Successful joke delivery	-	-	-
400	Bad request / invalid parameters	-	-	-
403	Rate limit exceeded	-	-	-
404	No jokes found for given filters	-	-	-
429	Too many requests	-	-	-
500	Internal server error	-	-	-

Frequently Asked Questions

The JokeAPI v2 accepts a query parameter blacklistFlags with comma-separated values (nsfw, religious, political, racist, sexist, explicit). The server filters jokes before responding, so blocked content never reaches the client. However, the classification is crowd-sourced. Some jokes may be mislabeled. For maximum safety in professional contexts, enable all filters except the category you specifically need.

The generator contains an embedded fallback dataset of 50 pre-screened jokes across all categories. When a fetch request fails (network error, HTTP 429, or timeout after 5 seconds), the tool switches to the local dataset automatically. A toast notification informs you that offline mode is active. Favorites and history continue to work normally since they use LocalStorage.

Yes. JokeAPI assigns persistent integer IDs to each joke. When you favorite a joke, the full joke object (including its ID) is stored in LocalStorage. This means favorites are immune to API changes. However, if JokeAPI removes or renumbers a joke, the local copy remains intact but may not match a future API lookup.

Applying multiple blacklist flags to a narrow category (e.g., Dark category with nsfw, explicit, and political all blacklisted) can reduce the available pool to zero. The API responds with a 404 and error flag. The tool detects this and displays a specific message suggesting you relax your filters. The Pun category is the least affected by filters since puns rarely trigger sensitivity flags.

Two-part jokes return as JSON with separate setup and delivery fields. The copy-to-clipboard function formats them with a line break separator. For automation, you can adapt the fetch logic. Note that JokeAPI enforces a rate limit of 120 requests per minute per IP. Exceeding this returns HTTP 429. For bulk retrieval, use their /joke endpoint with the amount parameter (max 10 per request).

No. All favorites and history are stored exclusively in your browser's LocalStorage. The only outbound request is the GET call to JokeAPI, which transmits your IP address (standard HTTP behavior) and the query parameters you selected. No cookies, analytics, or tracking scripts are used. Clearing your browser data will erase all stored favorites and history.