Joke API & Widget

Free REST API and embeddable widget for dad jokes. No sign-up required. Build Slack bots, websites, apps — whatever you want.

Embed a joke on your site

Two lines of HTML. That's it. Drop the widget on any webpage to show a fresh dad joke with a "Next joke" button — light or dark theme, filter by category. Every embed links back to GroanDeck automatically.

Why don't scientists trust atoms?

Because they make up everything!

Next jokegroandeck.com

<div data-groandeck></div>
<script src="https://groandeck.com/widget.js" defer></script>

Full widget options ↓

WordPress plugin

Install the official plugin to add the joke widget with a Gutenberg block or shortcode.

Download plugin (4 KB)v1.0.0 · Works with WordPress 5.0+

Installation

Download and unzip
Upload the groandeck-dad-jokes folder to /wp-content/plugins/
Activate in Plugins menu
Add the block or use [groandeck] shortcode

Rate limits

Tier	Limit	Auth
Free	30 requests/min	None
Free + Key	100 requests/min	`X-API-Key` header

Need higher limits? Get in touch.

Base URL

https://groandeck.com/api/v1

Endpoints

GET/api/v1/random

Get a random joke. Optionally filter by category.

Param	Type	Required	Description
`category`	string	No	Filter by category (e.g. "animals")

Example

curl https://groandeck.com/api/v1/random

Response

{
  "id": "a1b2c3d4-...",
  "setup": "Why don't scientists trust atoms?",
  "punchline": "Because they make up everything!",
  "tags": ["science"],
  "explanation": "Atoms are the building blocks of matter...",
  "url": "https://groandeck.com/j/why-dont-scientists-trust-atoms"
}

GET/api/v1/daily

Get today's featured joke. Changes daily.

Example

curl https://groandeck.com/api/v1/daily

Response

{
  "id": "a1b2c3d4-...",
  "setup": "Why did the scarecrow win an award?",
  "punchline": "Because he was outstanding in his field!",
  "tags": ["classic"],
  "explanation": "A play on 'outstanding'...",
  "url": "https://groandeck.com/j/why-did-the-scarecrow-win-an-award",
  "date": "2026-02-18"
}

GET/api/v1/jokes

List jokes with pagination and optional category filter.

Param	Type	Required	Description
`category`	string	No	Filter by category
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page, max 20 (default: 10)

Example

curl "https://groandeck.com/api/v1/jokes?category=food&limit=5"

Response

{
  "jokes": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "totalJokes": 118,
    "totalPages": 24,
    "hasNext": true,
    "hasPrev": false
  }
}

GET/api/v1/jokes/:id

Get a specific joke by its ID.

Param	Type	Required	Description
`id`	string	Yes	Joke UUID

Example

curl https://groandeck.com/api/v1/jokes/a1b2c3d4-...

Response

{ "id": "...", "setup": "...", "punchline": "...", ... }

GET/api/v1/categories

List all joke categories with counts.

Example

curl https://groandeck.com/api/v1/categories

Response

{
  "categories": [
    { "name": "puns", "jokeCount": 222 },
    { "name": "animals", "jokeCount": 128 },
    ...
  ]
}

Widget options

The widget is a self-contained <script> that fetches jokes from the API, renders a styled card, and includes a "Next joke" button. It works on any site — WordPress, Squarespace, static HTML, React, whatever.

Basic embed

<div data-groandeck></div>
<script src="https://groandeck.com/widget.js" defer></script>

Dark theme, filtered to animals

<div data-groandeck data-theme="dark" data-category="animals"></div>
<script src="https://groandeck.com/widget.js" defer></script>

Attribute	Values	Default
`data-theme`	"light" \| "dark"	light
`data-category`	Any category name	all

Why embed?

Automatic attribution link to GroanDeck on every page load
Fresh joke on every visit — no stale content
Light/dark theme matches any site design
Under 4 KB gzipped, no dependencies

Attribution

If you use the API or widget, a link back to groandeck.com is appreciated but not required on the free tier. The widget includes a small branded link by default.