Skip to content

API reference

Getting started

Authentication

This API is a free, public resource that requires no API keys or additional credentials.

Request headers

The Accept HTTP header communicates the type of media that should be in the response. Valid values include:

  • text/html
  • application/json
  • text/plain

The User-Agent header informs the API who is making the API requests and is required in order to use the icanhazdadjoke API.

icanhazdadjoke API - OpenAPI 3.0

Looking for some dad jokes? You've come to the right place!

Contact: bradley.s.dow@gmail.com

Servers

Description URL
Production server https://icanhazdadjoke.com

Endpoints

Search dad jokes

Description

Retrieve one or more dad jokes that meet the search criteria.

Input parameters

Parameter In Type Default Nullable Description
limit query integer No Number of results to return per page - If not specified, 20 results are returned by default (maximum of 30)
page query integer No Page number of results to retrieve - Works in tandem with the limit parameter
term query string No Search term - If not specified, all jokes are retrieved

Response 200 OK 

{
    "current_page": 1,
    "limit": 20,
    "next_page": 1,
    "previous_page": 1,
    "results": [
        {
            "id": "OCtWnGJtPuc",
            "joke": "Why is the new Kindle screen textured to look like paper? So you feel write at home."
        },
        {
            "id": "O7haxA5Tfxc",
            "joke": "Where do cats write notes? Scratch Paper!"
        },
        {
            "id": "EYo4TCAdUf",
            "joke": "I tried to write a chemistry joke, but could never get a reaction."
        },
        {
            "id": "SvPRCIeiNuc",
            "joke": "How does a dyslexic poet write? Inverse."
        }
    ],
    "search_term": "write",
    "status": 200,
    "total_jokes": 4,
    "total_pages": 1
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "properties": {
        "current_page": {
            "type": "integer",
            "example": 1
        },
        "limit": {
            "type": "integer",
            "example": 20
        },
        "next_page": {
            "type": "integer",
            "example": 1
        },
        "previous_page": {
            "type": "integer",
            "example": 1
        },
        "results": {
            "$ref": "#/components/schemas/jokesArray"
        },
        "search_term": {
            "type": "string",
            "example": "write"
        },
        "status": {
            "type": "integer",
            "example": 200
        },
        "total_jokes": {
            "type": "integer",
            "example": 4
        },
        "total_pages": {
            "type": "integer",
            "example": 1
        }
    }
}

Schemas

jokes

Name Type
id integer
joke string

jokesArray

Type: Array<jokes>

searchResults

Name Type
current_page integer
limit integer
next_page integer
previous_page integer
results jokesArray
search_term string
status integer
total_jokes integer
total_pages integer