API documentation

Version 2 of the Joke Daddabase HTTP API. All successful responses are JSON with a data object. Errors return JSON with an error string and an appropriate HTTP status code. Request and response bodies use UTF-8; responses include Content-Type: application/json.

Base URL

Every endpoint lives under this prefix:

https://jokes.lobaugh.net/api/v2

Joke object

Each joke includes the setup, punchline, stable string id, creation timestamp, and any tags from the CMS.

Field	Type	Description
id	string	Numeric id from the CMS, serialized as a string in JSON.
setup	string	The joke setup (question or lead-in).
punchline	string	The punchline or answer.
tags	array	Objects with slug and name for each tag; empty array if untagged.
createdAt	string	ISO 8601 timestamp when the joke was created.

GET/jokes

Returns a paginated list of jokes. You can narrow results with free-text search (matches setup and punchline) and/or a single tag slug. Use pagination to walk the full daddabase.

Query	Type	Description
page	integer	Page number, starting at 1. Default: 1.
limit	integer	Page size. Default: 20, maximum: 100.
q	string	Optional search string (setup and punchline). Alias: search.
tag	string	Optional filter by a single tag slug (e.g. dad-jokes).

Example request

curl -sS "https://jokes.lobaugh.net/api/v2/jokes?page=1&limit=5&q=programming&tag=dad-jokes"

Example response (200)

{
  "data": {
    "jokes": [
      {
        "id": "42",
      "setup": "Why do programmers prefer dark mode?",
      "punchline": "Because light attracts bugs.",
      "tags": [
        { "slug": "programming", "name": "Programming" },
        { "slug": "dad-jokes", "name": "Dad jokes" }
      ],
      "createdAt": "2025-01-15T12:00:00.000Z"
      }
    ],
    "page": 1,
    "limit": 5,
    "total": 128
  }
}

GET/jokes/<id>

Fetches one joke by its numeric id. Use the id from list or random responses. Invalid ids return 400; missing jokes return 404 with an error body.

Example request

curl -sS "https://jokes.lobaugh.net/api/v2/jokes/42"

Example response (200)

{
  "data": {
    "joke": {
      "id": "42",
      "setup": "Why do programmers prefer dark mode?",
      "punchline": "Because light attracts bugs.",
      "tags": [
        { "slug": "programming", "name": "Programming" },
        { "slug": "dad-jokes", "name": "Dad jokes" }
      ],
      "createdAt": "2025-01-15T12:00:00.000Z"
    }
  }
}

Example error (404)

{
  "error": "Not found"
}

GET/jokes/random

Returns a single joke chosen at random from the published collection. Suitable for "surprise me" buttons and bots. The choice is not fixed across the day—use /jokes/daily if you need the same joke all day.

Example request

curl -sS "https://jokes.lobaugh.net/api/v2/jokes/random"

Example response (200)

{
  "data": {
    "joke": {
      "id": "42",
      "setup": "Why do programmers prefer dark mode?",
      "punchline": "Because light attracts bugs.",
      "tags": [
        { "slug": "programming", "name": "Programming" },
        { "slug": "dad-jokes", "name": "Dad jokes" }
      ],
      "createdAt": "2025-01-15T12:00:00.000Z"
    }
  }
}

GET/jokes/daily

Returns today's featured joke. The same joke is returned for the entire calendar day in the configured timezone (see JOKE_DAILY_TIMEZONE in the app environment). The response includes meta.date, meta.timeZone, and meta.type so clients can show "Joke of the day for …" copy.

Example request

curl -sS "https://jokes.lobaugh.net/api/v2/jokes/daily"

Example response (200)

{
  "data": {
    "joke": {
      "id": "42",
      "setup": "Why do programmers prefer dark mode?",
      "punchline": "Because light attracts bugs.",
      "tags": [
        { "slug": "programming", "name": "Programming" },
        { "slug": "dad-jokes", "name": "Dad jokes" }
      ],
      "createdAt": "2025-01-15T12:00:00.000Z"
    },
    "meta": {
      "date": "2026-04-24",
      "timeZone": "America/Los_Angeles",
      "type": "joke_of_the_day"
    }
  }
}

Migrating from the legacy API

The previous site used /api/jokes with per_page and comma-separated tags. Version 2 uses /api/v2/jokes with limit, q (or search), and a single tag slug. Random and joke-of-the-day moved to /api/v2/jokes/random and /api/v2/jokes/daily.

← Back to the daddabase