# Official Joke API

> 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.

App · Misc References · 7 actions. Web page: https://docs.lodol.com/docs/integrations/official-joke-api

## Actions

### 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**

- `message` (text)
- `online` (true/false)
- `rate_limited` (true/false)
- `reachable` (true/false)
- `response_time_ms` (number)
- `status_code` (number)

**Example output**

```json
{
  "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_id`, text, required): The joke's numeric id. A full official-joke-api.appspot.com joke URL is also accepted.

**Outputs**

- `joke` (object)

**Example output**

```json
{
  "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_type`, text): 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**

- `joke` (object)
- `joke_type` (text)

**Example output**

```json
{
  "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_jokes` (number)
- `type_count` (number)
- `types` (list)

**Example output**

```json
{
  "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 (`count`, number): How many jokes to draw, from 1 to 100. Defaults to 10. From 1 to 100.
- Joke type (`joke_type`, text): 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 (`seed`, text): 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_count` (number)
- `joke_type` (text)
- `jokes` (list)
- `requested_count` (number)
- `seed` (text)

**Example output**

```json
{
  "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 (`date`, date): The day to pick a joke for. Leave empty for today in UTC, which is what a scheduled step wants.
- Joke type (`joke_type`, text): 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 (`seed`, text): 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**

- `date` (text)
- `joke` (object)
- `joke_type` (text)
- `pool_size` (number)
- `seed` (text)

**Example output**

```json
{
  "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 (`query`, text, required): The word or phrase to look for in setups and punchlines.
- Joke type (`joke_type`, text): Only search jokes of this type. Leave empty to search every joke.
- Number of results (`limit`, number): 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_type` (text)
- `match_count` (number)
- `matches` (list)
- `query` (text)
- `total_matches` (number)

**Example output**

```json
{
  "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
}
```