Official Joke API
App · Misc References · 7 actions
Pull jokes from the Official Joke API's open catalogue of several hundred setups and punchlines. Draw one at random or a batch of them, narrow to a type such as programming, knock-knock or dad, search every joke for a subject, look one up by id, or pick a joke of the day that stays the same all day so a scheduled post never tells two.
Actions
| Action | What it does |
|---|---|
| Check service status | Check whether the Official Joke API is answering, and how quickly. |
| Get a joke by id | Get one specific joke by its id, for re-reading a joke an earlier step found. |
| Get a random joke | Get one random joke, with its setup and punchline both separately and joined together ready to post. |
| Get joke types | List the joke types the service currently publishes and how many jokes each one holds, biggest first, so a step that filters by type knows what it can ask for and how much there is to draw on. |
| Get random jokes | Get several different jokes at once, up to 100, optionally all of one type. |
| Get the joke of the day | Pick one joke for a day and keep picking that same joke all day. |
| Search jokes | Find jokes about something: search every setup and punchline for a word or phrase, best match first. |
Check service status
Check whether the Official Joke API is answering, and how quickly. This is the one action that reports a problem as a value instead of failing the step, so a workflow can decide what to do about it. Being rate limited is reported separately from being down, since the service allows 100 requests every 15 minutes per address.
Inputs
None.
Outputs
messagetextonlinetrue/falserate_limitedtrue/falsereachabletrue/falseresponse_time_msnumberstatus_codenumber
Example output
{
"message": "The Official Joke API is up and answering.",
"online": true,
"rate_limited": false,
"reachable": true,
"response_time_ms": 142.7,
"status_code": 200
}Get a joke by id
Get one specific joke by its id, for re-reading a joke an earlier step found. Ids are positions in the service's joke file and are handed out when it restarts, so a joke inserted upstream shifts every id after it: store the joke itself, not its id, if it has to still mean the same thing next month.
Inputs
- Joke ID
joke_idtextRequired - The joke's numeric id. A full official-joke-api.appspot.com joke URL is also accepted.
Outputs
jokeobject
Example output
{
"joke": {
"id": 14,
"punchline": "He's adept at riffing in C#.",
"setup": "Why would a guitarist become a good programmer?",
"text": "Why would a guitarist become a good programmer?\nHe's adept at riffing in C#.",
"type": "programming"
}
}Get a random joke
Get one random joke, with its setup and punchline both separately and joined together ready to post. Narrow it to a type such as programming or dad, or leave the type empty to draw from the whole catalogue.
Inputs
- Joke type
joke_typetext - Only return jokes of this type. The service publishes general, programming, knock-knock and dad; run Get joke types for the current list. Leave empty to draw from every joke.
Outputs
jokeobjectjoke_typetext
Example output
{
"joke": {
"id": 14,
"punchline": "He's adept at riffing in C#.",
"setup": "Why would a guitarist become a good programmer?",
"text": "Why would a guitarist become a good programmer?\nHe's adept at riffing in C#.",
"type": "programming"
},
"joke_type": "programming"
}Get joke types
List the joke types the service currently publishes and how many jokes each one holds, biggest first, so a step that filters by type knows what it can ask for and how much there is to draw on.
Inputs
None.
Outputs
total_jokesnumbertype_countnumbertypeslist
Example output
{
"total_jokes": 451,
"type_count": 4,
"types": [
{
"joke_count": 380,
"type": "general"
},
{
"joke_count": 64,
"type": "programming"
},
{
"joke_count": 5,
"type": "knock-knock"
},
{
"joke_count": 2,
"type": "dad"
}
]
}Get random jokes
Get several different jokes at once, up to 100, optionally all of one type. No joke is drawn twice in the same batch. Give it a seed and the same seed draws the same jokes in the same order every time, so a run can be repeated; leave the seed empty for a fresh draw. Asking for more jokes of a type than exist returns all of them rather than failing.
Inputs
- Number of jokes
countnumber - How many jokes to draw, from 1 to 100. Defaults to 10.From 1 to 100.
- Joke type
joke_typetext - Only return jokes of this type. The service publishes general, programming, knock-knock and dad; run Get joke types for the current list. Leave empty to draw from every joke.
- Seed
seedtext - Any text you like. The same seed always draws the same jokes, so a workflow can be re-run and get the same batch. Leave empty for a different draw each time.
Outputs
joke_countnumberjoke_typetextjokeslistrequested_countnumberseedtext
Example output
{
"joke_count": 2,
"joke_type": null,
"jokes": [
{
"id": 1,
"punchline": "Dam.",
"setup": "What did the fish say when it hit the wall?",
"text": "What did the fish say when it hit the wall?\nDam.",
"type": "general"
},
{
"id": 14,
"punchline": "He's adept at riffing in C#.",
"setup": "Why would a guitarist become a good programmer?",
"text": "Why would a guitarist become a good programmer?\nHe's adept at riffing in C#.",
"type": "programming"
}
],
"requested_count": 2,
"seed": null
}Get the joke of the day
Pick one joke for a day and keep picking that same joke all day. A random draw gives a different joke on every call, so a daily workflow that retries, or that two people run an hour apart, tells two different jokes for the one day. This one is fixed by the date: the same date always gives the same joke, and tomorrow gives a different one. Add a seed of your own to have two workspaces tell different jokes on the same day.
Inputs
- Day
datedate - The day to pick a joke for. Leave empty for today in UTC, which is what a scheduled step wants.
- Joke type
joke_typetext - Only return jokes of this type. The service publishes general, programming, knock-knock and dad; run Get joke types for the current list. Leave empty to draw from every joke.
- Seed
seedtext - Any text you like, mixed into the day so that two workspaces running this on the same day get different jokes. Leave empty to share the day's joke with everyone else.
Outputs
datetextjokeobjectjoke_typetextpool_sizenumberseedtext
Example output
{
"date": "2026-08-25",
"joke": {
"id": 1,
"punchline": "Dam.",
"setup": "What did the fish say when it hit the wall?",
"text": "What did the fish say when it hit the wall?\nDam.",
"type": "general"
},
"joke_type": null,
"pool_size": 451,
"seed": "2026-08-25"
}Search jokes
Find jokes about something: search every setup and punchline for a word or phrase, best match first. A joke matches on the whole phrase, or on all of your words appearing somewhere in it, and each result says whether the match was in the setup or the punchline. The service has no search of its own, so this reads its whole catalogue and matches here.
Inputs
- Search for
querytextRequired - The word or phrase to look for in setups and punchlines.
- Joke type
joke_typetext - Only search jokes of this type. Leave empty to search every joke.
- Number of results
limitnumber - How many matches to return, from 1 to 100. Defaults to 10. The total number of matches is always reported, however many are returned.From 1 to 100.
Outputs
joke_typetextmatch_countnumbermatcheslistquerytexttotal_matchesnumber
Example output
{
"joke_type": "programming",
"match_count": 1,
"matches": [
{
"id": 14,
"matched_fields": [
"setup"
],
"punchline": "He's adept at riffing in C#.",
"setup": "Why would a guitarist become a good programmer?",
"text": "Why would a guitarist become a good programmer?\nHe's adept at riffing in C#.",
"type": "programming"
}
],
"query": "guitarist",
"total_matches": 1
}