JokeAPI - by          (loading)
This is a uniformly and carefully formatted RESTful joke API anyone can use without any API token, membership, registration or payment.
The usage is very simple and similar to other RESTful APIs and requires only basic knowledge of HTTP/HTTPS requests and JSON/XML/YAML.


If you are still using the old syntax which uses the joke_category header, please re-read this documentation to migrate to version 1.0.0's new syntax. To make this easier, some sections contain a red header that begins with Migration to 1.0.0 which contains more information on how to migrate.

I'm currently having problems with my DNS on my main domain so you might wanna use my backup domain (http://sv443.ddns.net/jokeapi/... (not HTTPS and slower)) if the main domain doesn't work.




This is what you'll be receiving from the API (note how a type: single joke only consists of a joke attribute, while a type: twopart joke has both a setup and a delivery):
{
    "category": "Programming",
    "type": "single",
    "joke": "I've got a really good UDP joke to tell you but I don't know if you'll get it.",
    "id": 0
}

OR

{
    "category": "Programming",
    "type": "twopart",
    "setup": "How many programmers does it take to screw in a light bulb?",
    "delivery": "None. It's a hardware problem.",
    "id": 1
}
Pretty easy, huh?   : )


Try it out here:

Warning! The jokes from the Dark category might be really, really dark, so if you get triggered by stuff like that, maybe don't send a request with that category.

curl -X GET "https://sv443.net/jokeapi/category/?blacklistFlags=
"



(Hold down CTRL to select multiple flags)

Result:

(Click send above)







Usage:

Migration to 1.0.0: Instead of putting the category in the header, put it in the URL path, just after the category endpoint.

To use the JokeAPI, send a GET request to the endpoint at https://sv443.net/jokeapi/category/[Category_Name] and make sure you provide the correct category name. Otherwise an error will be returned.
This category name has to correspond to any of the available joke categories (case sensitive!), which you can see by sending a GET request to this endpoint: https://sv443.net/jokeapi/categories.
The following is the result of a GET request to the above mentioned endpoint:

Examples:
























Flags:

Migration to 1.0.0: Now you can add these optional filters.

JokeAPI now supports an additional filter, the so called flags. These are additional properties of the JSON object and they indicate that a certain joke might not be suitable for certain people.
There's currently three flags:
To filter out jokes with certain flags, add the URL parameter ?blacklistFlags=[Comma separated Flags] (if there's no other question mark) or &blacklistFlags=[Comma separated Flags] (if there's already a question mark) to the final URL.

Examples:






















File Formats:

Migration to 1.0.0: Now you can request one of these optional file formats.

Version 1.0.0 adds another useful thing and that is the ability to choose the file format of the payload.
This feature works on every single endpoint and in the exact same way.
Currently supported file formats are:
To change the format of the data, simply add a ?format=json/xml/yaml to the URL if your URL doesn't contain a question mark, or &format=json/xml/yaml if it does.
The default value is JSON, so if you need your joke in JSON format you can also not add a format parameter at all. This also means that a misspelt format will give you your joke in JSON.

Examples:






















All Attributes:

Migration to 1.0.0: Only the id attribute was added.

These are all attributes at once with their description: {
    "category": "The category of the joke",
    "type": "single or twopart",
    "joke": "this property only exists if the type property is single",
    "setup": "this property is the setup of a joke with the type twopart",
    "delivery": "this property is the delivery of a joke with the type twopart",
    "nsfw": "will be true if a joke is potentially not safe for work or will not exist if not",
    "religious": "will be true if a joke is offensive against a religion or will not exist if not",
    "political": "will be true if a joke is potentially political or will not exist if not",
    "id": "(since v1.0.0) a unique ID each joke has - could be useful to not have the same joke twice in a row"
}





















Information Endpoint:

Migration to 1.0.0: This endpoint is one of the three new endpoints.

By sending a GET request to https://sv443.net/jokeapi/info (other formats are also supported), you'll receive some information about JokeAPI that could be useful for automation: (Loading) (sorry for the bad formatting, I made this syntax highlighting by patching together snippets and it doesn't work with more than one "JSON layer")




















Example with CURL:

curl -X GET "https://sv443.net/jokeapi/category/Any?blacklistFlags=nsfw"
This will return a joke from any category that is not NSFW.





Example with NodeJS:

var randomJoke;
var jokeCategory = "Any";
var format = "xml";
var blacklistFlags = "nsfw,political";

http.get({
    host: "https://sv443.net",
    path: `jokeapi/category/${jokeCategory}?blacklistFlags=${blacklistFlags}&format=${format}`
}).then(res => {
    randomJoke = JSON.parse(res);
});
The variable randomJoke is now a JSON object like the one at the top of this page





Example with jQuery:

var randomJoke;
var jokeCategory = "Miscellaneous";
var format = "xml";
var blacklistFlags = "nsfw";

$.ajax({
    method: "GET",
    url: `https://sv443.net/jokeapi/category/${jokeCategory}?blacklistFlags=${blacklistFlags}&format=${format}`,
    success: (data, status) => {
        randomJoke = JSON.parse(data);
    }
});
The variable randomJoke is now a JSON object like the one at the top of this page










Special Thanks:






Add
Joke