BYTETOOLS

Official Joke API

Free joke API with no key: random jokes with setup and punchline, filterable by type. Perfect for beginner projects. Tested curl example and live JSON.

No API key requiredCORS enabledHTTPSFree tier

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

What is the Official Joke API?

The Official Joke API is a free, key-free API that returns random jokes as JSON, each split into a `setup` and a `punchline`, with optional filtering by joke type such as general, programming or knock-knock.

This API is a staple of beginner tutorials for one reason: the response shape is ideal for teaching. Every joke arrives as a clean object with `setup` and `punchline` fields, which naturally demonstrates rendering two related values and sequencing a reveal.

It also supports fetching batches with `/jokes/ten` and filtering by type, so the same API can carry a tutorial from a single fetch all the way to list rendering and filtering without swapping data sources.

Quick facts

Base URL
https://official-joke-api.appspot.com
Authentication
No key or registration.
Rate limit
No published limit.
Pricing
Free and open source.
CORS
Enabled — callable directly from browser JavaScript
Official docs
Read the docs

How to use the Official Joke API

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

1. Fetch a single random joke

GET https://official-joke-api.appspot.com/random_joke

curl
curl 'https://official-joke-api.appspot.com/random_joke'
JavaScript (fetch)
const res = await fetch("https://official-joke-api.appspot.com/random_joke");
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://official-joke-api.appspot.com/random_joke", timeout=20)
res.raise_for_status()
print(res.json())
Response — HTTP 200
{
  "type": "general",
  "setup": "I had a dream that I was a muffler last night.",
  "punchline": "I woke up exhausted!",
  "id": 53
}

Parameters

ParameterTypeRequiredDescription
<type>pathOptionalFilter by type: general, programming, knock-knock or dad. programming
<count>pathOptionalUse /jokes/ten or /random_ten for batches. ten

Response fields

idinteger
Joke identifier.
typestring
Category, e.g. general or programming.
setupstring
The opening line of the joke.
punchlinestring
The payoff — usually revealed after a delay in UI.

What you can build with the Official Joke API

  • Build a first fetch/async tutorial project with a satisfying result
  • Add a lighthearted random joke widget to a site or Slack bot
  • Practise reveal animations and state transitions in a UI
  • Demonstrate list rendering by fetching ten jokes at once

Common errors and how to fix them

404

Unknown joke type in the path.

Fix: Valid types are general, programming, knock-knock and dad.

Occasional slow response

Hosted on free App Engine infrastructure that can cold start.

Fix: Set a generous timeout and handle the loading state properly.

Official Joke API — frequently asked questions

Is there a free joke API with no API key?

Yes. The Official Joke API returns random jokes as JSON with no key, no signup and no authentication, which makes it a common choice for beginner projects.

How do I get more than one joke at a time?

Request /jokes/ten or /random_ten, which return an array of ten jokes in a single response — useful for practising list rendering.

Can I filter jokes by category?

Yes. Add the type to the path, for example /jokes/programming/random, with general, programming, knock-knock and dad available.

Why are setup and punchline separate fields?

So your interface can reveal the punchline separately — the structure is deliberately designed for the classic click-to-reveal pattern.

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.

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