Wanna chat?

The JokeyBot has a REST API that you can use to integrate it into other applications. You're free to use the API, and it does not require authentication of any sort.

You do not require my permission to link to the JokeyBot, even for embedding it in a commercial application. If, however, I find that you're selling access to JokeyBot content (and not as an add-on or sidebar to an existing application), you will probably be blocked.

If you integrate JokeyBot with your app, won't you contact me and let me know? I'd love to provide a link to your application.

§1 Clean vs Dirty Joke Selection

The choice of clean vs. dirty jokes is yours to make. To access clean jokes, access the api at http://jokeybot.com. For dirty jokes, use http://dirty.jokeybot.com.

§2 Joke-getting APIs

§2.1 Get a random joke

A simple GET to /api/joke will fetch a random curated joke that has not been reported as objectionable by any users. The returned value is a JSON structure containing the joke, its current vote statistics, and tags that are attached to the joke.

 $ curl http://jokeybot.com/api/joke
 {
    "tags":[
        {"name":"puns","id":2},
        {"name":"riddles","id":1},
        {"name":"farming","id": 11}
    ],
    "joke":{
        "upvotes":1,
        "downvotes":0,
        "id":5,
        "text":"Why did the scarecrow win an award? Because he was outstanding in his field."
    }
 }

§2.2 Get a random joke from a collection

A GET to /api/joke/collection will fetch a random curated joke that has not been reported as objectionable by any users, which is tagged with the collection name you specify. If there are no jokes with that collection name, an empty JSON object is returned. The returned value is identical to the random-joke API.

§2.3 Get the Joke of the Day

§3 Voting APIs

The Upvote and Downvote APIs are both simple GET calls, with the parameter the id number of the joke, as delivered in the API call that retrieved it.

For both of the voting APIs, every IP address is rate-limited on the use of the API; a count is kept of votes, and once the limit is reached, the count is decremented slowly over time. If the IP request comes from an address that has been rate-limited in this fashion or has been blocked for other reasons (see the Code of Conduct for details), the API will return a 403 (Forbidden) status.

For both APIs, if you reference a joke ID that does not exist, the API will return a 404 (Not Found) status.

Both APIs return the current state of votes for that joke in a JSON structure.

§3.1 Upvote

 $ curl http://jokeybot.local/api/upvote/22
 {
    "id":22,
    "downvotes":12,
    "upvotes":1453
 }

§3.2 Downvote

 $ curl http://jokeybot.local/api/downvote/2822
 {
    "id":2822,
    "downvotes":163,
    "upvotes":9411
 }

§4 Joke Creation API

Coming soon!