Random Joke API: The Complete Guide

Need to add humor to your application? This guide covers everything you need to know about getting random jokes via API, including categories, joke formats, and implementation examples.

Types of Jokes

The API provides jokes across multiple categories to suit different audiences and contexts. All jokes are curated to be appropriate for general audiences unless you specifically request adult content.

Jokes are available in various styles from classic one-liners to elaborate setups with punchlines.

Joke Formats

Available joke categories and formats:

Dad Jokes

Classic family-friendly puns and groaners. Perfect for all ages and contexts.

Programming Jokes

Tech humor about coding, developers, and computer science. Great for dev tools and tech apps.

General Humor

Mixed category with various types of clean humor.

One-liners

Quick, single-sentence jokes perfect for UI constraints.

Setup/Punchline

Two-part jokes with a setup question and punchline answer. Good for interactive displays.

Using the Random Joke API

TinyFn provides a simple endpoint to get random jokes:

GET https://api.tinyfn.io/v1/random/joke?category=programming
Headers: X-API-Key: your-api-key

{
  "type": "twopart",
  "setup": "Why do programmers prefer dark mode?",
  "punchline": "Because light attracts bugs!",
  "category": "programming",
  "safe": true,
  "id": "prog_042"
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/random/joke?category=programming',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const joke = await response.json();
if (joke.type === 'twopart') {
  console.log(joke.setup);
  console.log(joke.punchline);
} else {
  console.log(joke.joke);
}

Python

import requests

response = requests.get(
    'https://api.tinyfn.io/v1/random/joke',
    params={'category': 'programming'},
    headers={'X-API-Key': 'your-api-key'}
)
joke = response.json()
print(f"{joke['setup']}\n{joke['punchline']}")

cURL

curl "https://api.tinyfn.io/v1/random/joke?category=programming" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Chat Bots: Add humor commands to Discord/Slack bots
• 404 Pages: Lighten the mood on error pages
• Loading Screens: Entertain users while waiting
• Daily Features: Joke of the day widgets
• Social Apps: Share buttons for jokes

Best Practices

1. Match your audience: Choose appropriate categories
2. Handle two-part jokes: Display setup and punchline separately
3. Use safe mode: Enable for public-facing applications
4. Don't overuse: Humor works best in moderation

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-random": {
      "url": "https://api.tinyfn.io/mcp/random/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all random tools available via MCP in our Random MCP Tools for AI Agents guide.