Joke API

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

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/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 },
    ...
  ]
}

Embeddable widget

Drop this snippet on any webpage to show a joke-of-the-day card with a "Next joke" button.

Basic

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

With options

<!-- Dark theme, animals only -->
<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

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.