Search Jokes.One  

Jokes API

  1. Home
  2. 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.

Here are the full features of the API

  • Joke of the day on various categories
  • Random Joke
  • Search and retrieve Jokes based on categories query term etc
  • Ability to retrive SFW jokes based on various flags such as dirty, racial etc
  • Ability to store and retrieve private jokes

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

You can get the joke of the day via our REST API. Knock Knock Joke of the day, Blonde Joke of the day, Animal joke of the day are supported.

GET /jod

Code Samples

function get_joke_of_the_day() {
    var xhttp = new XMLHttpRequest();
    xhttp.onreadystatechange = function() {
	 if (this.readyState == 4 && this.status == 200) {
	     // Access the result here
	     alert(this.responseText);
	 }
    };
    xhttp.open("GET", "https://api.jokes.one/jod?category=animal", true);
    xhttp.setRequestHeader("Content-type", "application/json");
    xhttp.setRequestHeader("X-JokesOne-Api-Secret", "YOUR API HERE");
    xhttp.send();
}

get_joke_of_the_day()
curl -X GET "https://api.jokes.one/jod" -H  "accept: application/json" -H  "content-type: application/json" -H  "X-JokesOne-Api-Secret: api_key"
function call_api($method, $url, $data = false,$api_key=null)
{
    $curl = curl_init();

    switch ($method)
    {
	case "POST":
	    curl_setopt($curl, CURLOPT_POST, 1);

	    if ($data)
		curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
	    break;
	case "PUT":
	    curl_setopt($curl, CURLOPT_PUT, 1);
	    break;
	default:
	    if ($data)
		$url = sprintf("%s?%s", $url, http_build_query($data));
    }

    $headers = [
	'Content-Type: application/json'
	];
    if ( !empty($api_key))
	$headers[] = 'X-JokesOne-Api-Secret: '. $api_key;

    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

    $result = curl_exec($curl);

    curl_close($curl);

    return $result;
}

$jod_result = call_api("GET","https://api.jokes.one/jod?category=jod",false,null);

print_r($jod_result);
import requests


url = 'https://api.jokes.one/jod?category=knock-knock'
api_token = "YOUR API KEY HERE"
headers = {'content-type': 'application/json',
	   'X-JokesOne-Api-Secret': format(api_token)}

response = requests.get(url, headers=headers)
#print(response)
#print(response.text)
jokes=response.json()['contents']['jokes'][0]
print(jokes)
var request = URLRequest(url: URL(string: "https://api.jokes.one/jod")!)
request.httpMethod = "GET"
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("application/json", forHTTPHeaderField: "Accept")
request.addValue("YOUR API KEY HERE", forHTTPHeaderField: "X-JokesOne-Api-Secret")

URLSession.shared.dataTask(with: request, completionHandler: { data, response, error -> Void in
    do {
        print(data!)
        print(response!)
        let jsonDecoder = JSONDecoder()
        // Access the response here by using json model class
        // You can autogenerate Json4Swift_Base swift class below by pasting the JSON response in
        // the webpage http://www.json4swift.com
        let responseModel = try jsonDecoder.decode(Json4Swift_Base.self, from: data!)
        print(responseModel)
    } catch {
        print("JSON Serialization error")
    }
}).resume()
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.PrintStream;
import java.net.URL;
import java.net.URLConnection;
import java.net.HttpURLConnection;

public class get_jod {

    public static void main(String[] args) throws IOException {
        URL url = new URL("https://api.jokes.one/jod?category=blonde");

        try{
            //make connection
            HttpURLConnection urlc = (HttpURLConnection) url.openConnection();
            urlc.setRequestMethod("GET");
            // set the content type
            urlc.setRequestProperty("Content-Type", "application/json");
            urlc.setRequestProperty("X-JokesOne-Api-Secret", "YOUR API KEY HERE");
            System.out.println("Connect to: " + url.toString());
            urlc.setAllowUserInteraction(false);
            urlc.connect();

            //get result
            BufferedReader br = new BufferedReader(new InputStreamReader(urlc.getInputStream()));
            String l = null;
            while ((l=br.readLine())!=null) {
                System.out.println(l);
            }
            br.close();
        } catch (Exception e){
            System.out.println("Error occured");
            System.out.println(e.toString());
        }
    }

}
using System;
using System.IO;
using System.Net;

namespace Jokes.One
{
    public class JokeOfTheDay
    {
        public static void Main()
        {
            // Create a request for the URL.
            WebRequest request = WebRequest.Create(
              "https://api.jokes.one/jod?category=knock-knock");

            request.Headers.Add("X-JokesOne-Api-Secret", "YOUR API KEY HERE");

            // Get the response.
            WebResponse response = request.GetResponse();
            // Display the status.
          //  Console.WriteLine(((HttpWebResponse)response).StatusDescription);

            // Get the stream containing content returned by the server.
            // The using block ensures the stream is automatically closed.
            using (Stream dataStream = response.GetResponseStream())
            {
                // Open the stream using a StreamReader for easy access.
                StreamReader reader = new StreamReader(dataStream);
                // Read the content.
                string responseFromServer = reader.ReadToEnd();
                // Display the content.
                Console.WriteLine(responseFromServer);
            }

            // Close the response.
            response.Close();
        }
    }
}

Response

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

{
  "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"
  }
}
<response>
  <success>
    <total>1</total>
  </success>
  <contents>
      <jokes>
         <description>Joke of the day </description>
         <language>en</language>
         <background/>
         <category>jod</category>
         <date>2019-08-31</date>
         <joke>
              <title>Knock Knock - Opera who?</title>
              <lang>en</lang>
              <length>111</length>
              <clean>1</clean>
              <racial>0</racial>
              <date>2019-08-31</date>
              <id>oFr2gwJ7UpCrRffHKbXksQeF</id>
              <text>Knock Knock

			Who's there?

			Opera!

			Opera who?

			Opera-tunity, and you thought opportunity only knocked once!

             </text>
          </joke>
      </jokes>
    <copyright>2019-20 https://jokes.one</copyright>
  </contents>
</response>
parseResponse(
    {
       "meta":{
                "Access-Control-Allow-Origin":"*",
                "X-Auth-Status":"true",
                "X-RateLimit-Limit":"10 per hour",
                "X-RateLimit-Remaining":"2",
                "Cache-Control":"private, max-age=43200, pre-check=86400, post-check=43200",
                "Expires":"Sat, 31 Aug 2019 13:39:34 GMT",
                "Content-Type":"text\/javascript; charset=utf-8",
                "Content-Language":"en-US"
        },
       "data": {
               "success":{"total":1},
               "contents":{
                    "jokes":[{"description":"Joke of the day ","language":"en","background":"","category":"jod","date":"2019-08-31","joke":{"title":"Knock Knock - Opera who?","lang":"en","length":"111","clean":"1","racial":"0","date":"2019-08-31","id":"oFr2gwJ7UpCrRffHKbXksQeF","text":"Knock Knock\r\nWho's there?\r\nOpera!\r\nOpera who?\r\nOpera-tunity, and you thought opportunity only knocked once!\r\n\r\n"}}],"copyright":"2019-20 https:\/\/jokes.one"
                }
         }
    }
);

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

Code Samples

function get_joke_of_the_day() {
    var xhttp = new XMLHttpRequest();
    xhttp.onreadystatechange = function() {
	 if (this.readyState == 4 && this.status == 200) {
	     // Access the result here
	     alert(this.responseText);
	 }
    };
    xhttp.open("GET", "https://api.jokes.one/jod/categories", true);
    xhttp.setRequestHeader("Content-type", "application/json");
    xhttp.setRequestHeader("X-JokesOne-Api-Secret", "YOUR API HERE");
    xhttp.send();
}

get_joke_of_the_day()
curl -X GET "https://api.jokes.one/jod/categories" -H  "accept: application/json" -H  "content-type: application/json" -H  "X-JokesOne-Api-Secret: api_key"
function call_api($method, $url, $data = false,$api_key=null)
{
    $curl = curl_init();

    switch ($method)
    {
	case "POST":
	    curl_setopt($curl, CURLOPT_POST, 1);

	    if ($data)
		curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
	    break;
	case "PUT":
	    curl_setopt($curl, CURLOPT_PUT, 1);
	    break;
	default:
	    if ($data)
		$url = sprintf("%s?%s", $url, http_build_query($data));
    }

    $headers = [
	'Content-Type: application/json'
	];
    if ( !empty($api_key))
	$headers[] = 'X-JokesOne-Api-Secret: '. $api_key;

    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

    $result = curl_exec($curl);

    curl_close($curl);

    return $result;
}

$jod_result = call_api("GET","https://api.jokes.one/jod/categories",false,null);

print_r($jod_result);
import requests


url = 'https://api.jokes.one/jod/categories'
api_token = "YOUR API KEY HERE"
headers = {'content-type': 'application/json',
	   'X-JokesOne-Api-Secret': format(api_token)}

response = requests.get(url, headers=headers)
#print(response)
#print(response.text)
animaljod=response.json()['contents']['categories']['animal']
print(animaljod)
var request = URLRequest(url: URL(string: "https://api.jokes.one/jod/categories")!)
request.httpMethod = "GET"
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("application/json", forHTTPHeaderField: "Accept")
request.addValue("YOUR API KEY HERE", forHTTPHeaderField: "X-JokesOne-Api-Secret")

URLSession.shared.dataTask(with: request, completionHandler: { data, response, error -> Void in
    do {
        print(data!)
        print(response!)
        let jsonDecoder = JSONDecoder()
        // Access the response here by using json model class
        // You can autogenerate Json4Swift_Base swift class below by pasting the JSON response in
        // the webpage http://www.json4swift.com
        let responseModel = try jsonDecoder.decode(Json4Swift_Base.self, from: data!)
        print(responseModel)
    } catch {
        print("JSON Serialization error")
    }
}).resume()
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.PrintStream;
import java.net.URL;
import java.net.URLConnection;
import java.net.HttpURLConnection;

public class get_jod {

    public static void main(String[] args) throws IOException {
        URL url = new URL("https://api.jokes.one/jod/categories");

        try{
            //make connection
            HttpURLConnection urlc = (HttpURLConnection) url.openConnection();
            urlc.setRequestMethod("GET");
            // set the content type
            urlc.setRequestProperty("Content-Type", "application/json");
            urlc.setRequestProperty("X-JokesOne-Api-Secret", "YOUR API KEY HERE");
            System.out.println("Connect to: " + url.toString());
            urlc.setAllowUserInteraction(false);
            urlc.connect();

            //get result
            BufferedReader br = new BufferedReader(new InputStreamReader(urlc.getInputStream()));
            String l = null;
            while ((l=br.readLine())!=null) {
                System.out.println(l);
            }
            br.close();
        } catch (Exception e){
            System.out.println("Error occured");
            System.out.println(e.toString());
        }
    }

}
using System;
using System.IO;
using System.Net;

namespace Jokes.One
{
    public class JokeOfTheDayCategories
    {
        public static void Main()
        {
            // Create a request for the URL.
            WebRequest request = WebRequest.Create(
              "https://api.jokes.one/jod/categories");

            request.Headers.Add("X-JokesOne-Api-Secret", "YOUR API KEY HERE");

            // Get the response.
            WebResponse response = request.GetResponse();
            // Display the status.
          //  Console.WriteLine(((HttpWebResponse)response).StatusDescription);

            // Get the stream containing content returned by the server.
            // The using block ensures the stream is automatically closed.
            using (Stream dataStream = response.GetResponseStream())
            {
                // Open the stream using a StreamReader for easy access.
                StreamReader reader = new StreamReader(dataStream);
                // Read the content.
                string responseFromServer = reader.ReadToEnd();
                // Display the content.
                Console.WriteLine(responseFromServer);
            }

            // Close the response.
            response.Close();
        }
    }
}

Response

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

{
  "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"
  }
}
<response>
    <success>
            <total>3</total>
   </success>
   <contents>
       <categories>
              <name>jod</name>
              <description>Joke of the day </description>
              <language>en</language>
              <background/>
        </categories>
        <categories>
                <name>animal</name>
                <description>Animal Joke of the day </description>
                <language>en</language>
                <background/>
        </categories>
        <categories>
              <name>blonde</name>
              <description>Blonde joke of the day!</description>
              <language>en</language>
             <background/>
        </categories>
      <copyright>2019-20 https://jokes.one</copyright>
   </contents>

</response>
parseResponse( {
        "meta":{
              "Access-Control-Allow-Origin":"*",
              "X-Auth-Status":"true",
              "X-RateLimit-Limit":"10 per hour",
              "X-RateLimit-Remaining":"8",
              "Cache-Control":"private, max-age=10000, must-revalidate",
              "Expires":"Sat, 31 Aug 2019 20:24:41 GMT",
              "Content-Type":"text\/javascript; charset=utf-8",
              "Content-Language":"en-US"
         },
        "data": {
             "success":{"total":3},
             "contents":{
                "categories":[
                    {"name":"jod","description":"Joke of the day ","language":"en","background":""},
                    {"name":"animal","description":"Animal Joke of the day ","language":"en","background":""},
                    {"name":"blonde","description":"Blonde joke of the day!","language":"en","background":""}
                 ],
                 "copyright":"2019-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.

Swagger UI
Error

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
Subscribe

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
Subscribe

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
Subscribe