API

icanhazdadjoke.com can be used as an API for fetching a random joke, a specific joke, or searching for jokes in a variety of formats.

Calling the API

Authentication

No authentication is required to use the icanhazdadjoke.com API. Enjoy :)

API response format

All API endpoints follow their respective browser URLs, but we adjust the response formatting to be more suited for an API based on the provided HTTP Accept header.

Accepted Accept headers:

text/html - HTML response (default response format)
application/json - JSON response
text/plain - Plain text response

Note: Requests made via curl which do not set an Accept header will respond with text/plain by default.

Custom user agent

If you intend on using the icanhazdadjoke.com API we kindly ask that you set a custom User-Agent header for all requests.

Setting a custom User-Agent header for your code will help us be able to better monitor the usage of the API and identify potential bad actors.

A good user agent should include the name of the library or website that is accessing the API along with a URL/e-email where someone can be contacted regarding the library/website.

For example: curl -H "User-Agent: My Library (https://github.com/username/repo)" https://icanhazdadjoke.com/

Endpoints

Fetch a random dad joke

GET https://icanhazdadjoke.com/ fetch a random dad joke.

Fetching a random joke as JSON:

$ curl -H "Accept: application/json" https://icanhazdadjoke.com/
{
  "id": "R7UfaahVfFd",
  "joke": "My dog used to chase people on a bike a lot. It got so bad I had to take his bike away.",
  "status": 200
}

Fetching a random joke as text:

$ curl -H "Accept: text/plain" https://icanhazdadjoke.com/
  My dog used to chase people on a bike a lot. It got so bad I had to take his bike away.

Fetch a random dad joke as a Slack message

GET https://icanhazdadjoke.com/slack fetch random dad joke formatted for Slack.

This endpoint is used by the icanhazdadjoke Slack app but can be used by third parties who need to receive a random joke formatted as a Slack message.

This endpoint will only ever return JSON.

$ curl https://icanhazdadjoke.com/slack
{
  "attachments": [
    {
      "fallback": "What kind of magic do cows believe in? MOODOO.",
      "footer": " - ",
      "text": "What kind of magic do cows believe in? MOODOO."
    }
  ],
  "response_type": "in_channel",
  "username": "icanhazdadjoke"
}

Fetch a dad joke

GET https://icanhazdadjoke.com/j/<joke_id> fetch a specific dad joke.

Fetching a joke as JSON:

$ curl -H "Accept: application/json" https://icanhazdadjoke.com/j/R7UfaahVfFd
{
  "id": "R7UfaahVfFd",
  "joke": "My dog used to chase people on a bike a lot. It got so bad I had to take his bike away.",
  "status": 200
}

Fetching a joke as text:

$ curl -H "Accept: text/plain" https://icanhazdadjoke.com/j/R7UfaahVfFd
  My dog used to chase people on a bike a lot. It got so bad I had to take his bike away.

Fetch a dad joke as an image

GET https://icanhazdadjoke.com/j/<joke_id>.png fetch a dad joke as an image.

<img src="https://icanhazdadjoke.com/j/R7UfaahVfFd.png" />

Search for dad jokes

GET https://icanhazdadjoke.com/search - search for dad jokes.

This endpoint accepts the following optional query string parameters:

page - which page of results to fetch (default: 1)
limit - number of results to return per page (default: 20) (max: 30)
term - search term to use (default: list all jokes)

Receive search results back as JSON:

$ curl -H "Accept: application/json" https://icanhazdadjoke.com/search
{
  "current_page": 1,
  "limit": 20,
  "next_page": 2,
  "previous_page": 1,
  "results": [
    {
      "id": "M7wPC5wPKBd",
      "joke": "Did you hear the one about the guy with the broken hearing aid? Neither did he."
    },
    {
      "id": "MRZ0LJtHQCd",
      "joke": "What do you call a fly without wings? A walk."
    },
    ...
    {
      "id": "usrcaMuszd",
      "joke": "What's the worst thing about ancient history class? The teachers tend to Babylon."
    }
  ],
  "search_term": "",
  "status": 200,
  "total_jokes": 307,
  "total_pages": 15
}

Receive search results back as text:

$ curl -H "Accept: text/plain" https://icanhazdadjoke.com/search
Did you hear the one about the guy with the broken hearing aid? Neither did he.
What do you call a fly without wings? A walk.
When my wife told me to stop impersonating a flamingo, I had to put my foot down.
What do you call someone with no nose? Nobody knows.
What time did the man go to the dentist? Tooth hurt-y.
Why can’t you hear a pterodactyl go to the bathroom? The p is silent.
How many optometrists does it take to change a light bulb? 1 or 2? 1... or 2?
I was thinking about moving to Moscow but there is no point Russian into things.
Why does Waldo only wear stripes? Because he doesn't want to be spotted.
Do you know where you can get chicken broth in bulk? The stock market.
I used to work for a soft drink can crusher. It was soda pressing.
A ghost walks into a bar and asks for a glass of vodka but the bar tender says, “sorry we don’t serve spirits”
I went to the zoo the other day, there was only one dog in it. It was a shitzu.
I gave all my dead batteries away today, free of charge.
Why are skeletons so calm? Because nothing gets under their skin.
There’s a new type of broom out, it’s sweeping the nation.
Why don’t seagulls fly over the bay? Because then they’d be bay-gulls!
What did celery say when he broke up with his girlfriend? She wasn't right for me, so I really don't carrot all.
Q: What’s 50 Cent’s name in Zimbabwe? A: 400 Million Dollars.
What's the worst thing about ancient history class? The teachers tend to Babylon.

Search through jokes with a search term:

$ curl -H "Accept: application/json" "https://icanhazdadjoke.com/search?term=hipster"
{
  "current_page": 1,
  "limit": 20,
  "next_page": 1,
  "previous_page": 1,
  "results": [
    {
      "id": "GlGBIY0wAAd",
      "joke": "How much does a hipster weigh? An instagram."
    },
    {
      "id": "xc21Lmbxcib",
      "joke": "How did the hipster burn the roof of his mouth? He ate the pizza before it was cool."
    }
  ],
  "search_term": "hipster",
  "status": 200,
  "total_jokes": 2,
  "total_pages": 1
}

GraphQL

https://icanhazdadjoke.com/graphql - GraphQL query endpoint

GraphQL schema:

schema {
  query Query
}

type Query {
  joke(query: String): Joke
}

type Joke {
  id ID
  joke String
  permalink String
}

Example query:

$ curl -X POST -d '{"query": "query { joke {id joke permalink } }"}' -H "Content-Type: application/json" https://icanhazdadjoke.com/graphql
{
  "data": {
    "joke": {
      "id": "1DQZDY0gVnb",
      "joke": "What is a centipedes's favorite Beatle song?  I want to hold your hand, hand, hand, hand...",
      "permalink": "https://icanhazdadjoke.com/j/1DQZDY0gVnb"
    }
  }
}

See GraphQL - Serving over HTTP for more information on accessing this endpoint.