Jokes API

Jokes One joke API is a full featured jokes API that gives access to our jokes platform. You want to build an app or integrate humor into your workflow / applications you are in the right place. Drop us note if the plans below doesn't fullfill your usecase. We can create a custom plan for your use case.

Subscribe

Jokes One Joke API Basic

$9.99/mo

No contracts. Anytime cancellation.
1 API Key
1000 API Calls / day
Best in class backend tools
Easy to use REST API
Immediate provisioning

Jokes One Joke API Premium

$24.99/mo

No contracts. Anytime cancellation.
1 API Key
5000 API Calls / day
Best in class backend tools
Easy to use REST API
Immediate provisioning

Jokes One Joke API Ultra

$49.99/mo

No contracts. Anytime cancellation.
1 API Key
12500 API Calls / day
Best in class backend tools
Easy to use REST API
Immediate provisioning

API End Points

The end point for connecting : If you subscribe directly from us use this endpoint.
		https://api.jokes.one
		

Ratelimiting

Some of our API calls are public. To maintain our service level we ratelimit the number of API calls. For public API calls this is 60 API calls a day with distribution of 5 calls an hour. For paid plans this limit is increased according to the service level described in the plan.

Authentication

For public calls you don't need to pass any API key. Just invoke the endpoint (see examples below). For paid subscriptions you need to pass the API key.

Currently we support API Key based authentication. Please set a request header 'X-JokesOne-Api-Secret' with value of your API key. Alternatively you can also pass api_key= as a request parameter, though we strongly discourage this mode of passing the key.

API Documentation

Response formats

The api endpoints support the following formats:
  • JSON
  • XML
  • JSONP

Joke of the day Free

This portion of our REST API is available for public. You are required to credit jokes.one if you are using the free version.

Joke of the day categories

To get the the categories supported by joke of the day service you can use this endpoint.

GET /jod/categories

In curl this looks like the following :

curl -X GET "https://api.jokes.one/jod/categories" -H "accept: application/xml" -H "content-type: application/json" -H "X-JokesOne-Api-Secret: api_key"

The above calls will result in a response like the following.

GET /jod/categories
 
{
  "success": {
    "total": 3
  },
  "contents": {
    "categories": {
      "jod": {
        "category": "jod",
        "title": "Joke of the day ",
        "description": "Joke of the day ",
        "background": ""
      },
      "animal": {
        "category": "animal",
        "title": "Animal Joke of the day ",
        "description": "Animal Joke of the day ",
        "background": ""
      },
      "blonde": {
        "category": "blonde",
        "title": "Blonde joke of the day!",
        "description": "Blonde joke of the day!",
        "background": ""
      }
    },
    "copyright": "2018-20 https://jokes.one"
  }
}
     

Joke of the day

GET /jod

In curl this looks like the following :

curl -X GET "https://api.jokes.one/jod" -H "accept: application/xml" -H "content-type: application/json" -H "X-JokesOne-Api-Secret: api_key"

The above calls will result in a response like the following.

GET /jod
{
  "success": {
    "total": 1
  },
  "contents": {
    "jokes": [
      {
        "category": "jod",
        "title": "Joke of the day ",
        "description": "Joke of the day ",
        "background": "",
        "date": "2019-01-23",
        "joke": {
          "title": "Courtship Signals",
          "length": "83",
          "clean": "1",
          "racial": "0",
          "date": "2019-01-23",
          "id": "He3_WpaNfBV1Hs7zMLsR4QeF",
          "text": "Q. Why shouldn't you marry a tennis player?\r\nA. Because Love means nothing to them."
        }
      }
    ],
    "copyright": "2018-20 https://jokes.one"
  }
} 
     

Jokes Paid

Search for Joke

Search for jokes with key word

You can search for jokes with a given keyword. To get a joke with the term knock knock in it add a parameter "query=knock knock" to the call and it will return a random joke with pattern "knock knock" in it.

GET /joke/search

This would translate in to curl like the following:

curl -X GET "https://api.jokes.one/joke/search?query=knock-knock" -H "accept: application/json" -H "content-type: application/json" -H "X-JokesOne-Api-Secret: api_key"

The above call would return a joke which has a phrase "knock knock".

GET /joke/search
{
  "success": {
    "total": 1
  },
  "contents": {
    "jokes": [
      {
        "title": "Mark Bookspan",
        "length": "70",
        "clean": null,
        "racial": null,
        "id": "_T_fW9BD2_FaHaTr5IrlsAeF",
        "text": "\nKnock-knock\n Who's there? \n\n\nMark Bookspan \n\n\nQuick, bolt the door!\n\n"
      }
    ],
    "copyright": "2019-20 https://jokes.one"
  }
}
     

Search for jokes in specific category

You can search for jokes in a specific category. Categories are managed using tags in the backend. To get a dad joke you can specify a parameter "category=dad".

GET /joke/search

This would translate in to curl like the following:

curl -X GET "https://api.jokes.one/joke/search?category=dad" -H "accept: application/json" -H "content-type: application/json" -H "X-JokesOne-Api-Secret: api_key"

The above call would return a joke in dad jokes category

GET /joke/search
{
  "success": {
    "total": 1
  },
  "contents": {
    "jokes": [
      {
        "title": "Useless Elephant",
        "length": "64",
        "clean": "0",
        "racial": "0",
        "id": "2cT1g9kqoeCO9FqhRnHObgeF",
        "text": "What do you call an elephant that doesn't matter? An irrelephant"
      }
    ],
    "copyright": "2019-20 https://jokes.one"
  }
}
     

To search for programming jokes you can do something like this.

curl -X GET "https://api.jokes.one/joke/search?category=programming" -H "accept: application/json" -H "content-type: application/json" -H "X-JokesOne-Api-Secret: api_key"

Search for jokes with specific length restrictions

You can use "minlen" and "maxlen" parameters in combination with other parameters like "query" or "category" to restrict the length of the joke that is returned.

Get a random Joke

To get a random joke call the following endpoint. This API endpoint doesn't require any parameters.

GET /joke/random

This would translate in to curl like the following:

curl -X GET "https://api.jokes.one/joke/random" -H "accept: application/json" -H "content-type: application/json" -H "X-JokesOne-Api-Secret: api_key"

The above call would return the following response.

GET /joke/random
{
  "success": {
    "total": 1
  },
  "contents": {
    "jokes": [
      {
        "title": "A blonde was bragging about her knowledge of state capitals.",
        "length": "208",
        "clean": "1",
        "racial": null,
        "id": "8_EqzUsq9YKt1b8jhNsc3geF",
        "text": "A blonde was bragging about her knowledge of state capitals. She proudly says, Go ahead, ask me, I know all of them. A friend says, OK, what's the capital of Wisconsin? The blonde replies, Oh, that's easy: W."
      }
    ],
    "copyright": "2018-20 https://jokes.one"
  }
}
     

Create a new Joke

PUT /joke

In curl this looks like the following :

curl -X PUT "https://api.jokes.one/joke?title=Knock%20Knock&text=Knock%20Knock%2C%20Who%20is%20there%3F%20Silence.%20&tags=silence%2C%20knock-knock" -H "accept: application/json" -H "content-type: application/json" -H "X-JokesOne-Api-Secret: api_key"

The response will return the id of the joke that was just added to your private collection.

PUT /joke
   {
        "success": {"total": 1  },
        "content": 
             {
                "joke": {"id": "0tztT1wYHRzdTf7jIccAzweF"}
             } 
   }
     

Delete a Joke

DELETE /joke

In curl this looks like the following :

curl -X DELETE "https://api.jokes.one/joke?id=0tztT1wYHRzdTf7jIccAzweF" -H "accept: application/json" -H "content-type: application/json" -H "X-JokesOne-Api-Secret: api_key"
The response will return the id of the joke that was just added to your private collection.
DELETE /joke
   {
        "success": { "total": 1  },
        "content": "Joke with id 0tztT1wYHRzdTf7jIccAzweF is deleted"
   }
     

Get a specific Joke

GET /joke

In curl this looks like the following :

curl -X GET "https://api.jokes.one/joke?id=mL_RDAbKC_3fHncrxPLxDweF" -H "accept: application/json" -H "content-type: application/json" -H "X-JokesOne-Api-Secret: api_key"

The above calls will result in a response like the following.

GET /joke
{
  "success": {
    "total": 1
  },
  "contents": {
    "jokes": [
      {
        "title": "So that's the reason",
        "length": "89",
        "clean": 1, 
        "racial": null,
        "id": "mL_RDAbKC_3fHncrxPLxDweF",
        "text": "Why did the physics teacher break up with the biology teacher? \n\nThere was no chemistry.\n"
      }
    ],
    "copyright": "2018-20 https://jokes.one"
  }
}
     

API Console

The following are the API calls you can make. You can try out / test the calls right from this page. Please note, javascript needs to be enabled to see the documentation below.