Documentation

Here you have detailed documentation of all available API functions. To get started, you can make the sample request for each endpoint, download an SDK, or run in Postman (see bottom of left navigation).

Search Jokes

With over 50,000 jokes, you should find something for any occasion. There are 27 categories to choose from but you can also search for very specific words within jokes.

GET
https://api.humorapi.com/jokes/search
Example Request and Response
GET
https://api.humorapi.com/jokes/search?number=3&keywords=horse,man
{
    "jokes": [
        {
            "id": 35642,
            "joke": "A man walked into a cowboy bar and ordered a beer just as President Bush appeared on the television. After a few sips, he looked up at the television and mumbled, \"Now, there's the biggest horse's ass I've ever seen.\" A customer at the end of the bar quickly stood up, walked over to him, and decked him. A few minutes later, as the man was finishing his beer, Mrs. Bush appeared \n on the television. \"She's a horse's ass too,\" the man. This time, a customer at the other end of the bar quickly stood up, walked over \n to him, and knocked him off his stool. \"Damn it!\" the man said, climbing back up to the bar. \"This must be Bush country!\" \"Nope,\" the bartender replied. \"Horse country!\""
        },
        {
            "id": 39052,
            "joke": "The General went out to find that none of his G.I.s were there. One finally ran up, panting heavily.\"Sorry, sir! I can explain, you see I had a date and it ran a little late. I ran to the bus but missed it, I hailed a cab but it broke down, found a farm, bought a horse but it dropped dead, ran 10 miles, and now I`m here.\"The General was very skeptical about this explanation but at least he was here so he let the G.I. go. Moments later, eight more G.I.s came up to the general panting, he asked them why they were late.\"Sorry, sir! I had a date and it ran a little late, I ran to the bus but missed it, I hailed a cab but it broke down, found a farm, bought a horse but it dropped dead, ran 10 miles, and now I`m here.\"The General eyed them, feeling very skeptical but since he let the first guy go, he let them go, too. A ninth G.I. jogged up to the General, panting heavily.\"Sorry, sir! I had a date and it ran a little late, I ran to the bus but missed it, I hailed a cab but...\"\"Let me guess,\" the General interrupted, \"it broke down.\"\"No,\" said the G.I., \"there were so many dead horses in the road, it took forever to get around them.\""
        },
        {
            "id": 41701,
            "joke": "A man has a racehorse, never won a race. Man in disgust says, Horse, you win today or you pull a milk wagon tomorrow morning.\" The starting gate opens, the horses take-off, they move the gate away and there lays his horse asleep on the track. He kicks the horse and asks, \"WHY ARE YOU SLEEPING. The horse, half asleep says, \"I have to get up at three in the morning.\""
        }
    ],
    "available": 541
}

Random Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

GET
https://api.humorapi.com/jokes/random
Example Request and Response
GET
https://api.humorapi.com/jokes/random
{
    "id": 38242,
    "joke": "Q: How many divorced men does it take to screw in a light bulb?\nA: None, the sockets go with the house."
}

Analyze Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

POST
https://api.humorapi.com/jokes/analyze
Example Request Body
POST
https://api.humorapi.com/jokes/analyze
What do you call a deer without eyes? No ideer.
Response
{
    "joke": "What do you call a deer without eyes? No ideer.",
    "tags": [
        "ANIMAL"
    ]
}

Submit Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

POST
https://api.humorapi.com/jokes
Example Request Body
POST
https://api.humorapi.com/jokes
What do you call a deer without eyes? No ideer.
Response
{
    "joke": {
        "id": 52625,
        "joke": "What do you call a deer without eyes? No ideer.",
        "tags": [
            "ANIMAL"
        ]
    },
    "message": "Thanks for submitting the joke. We will evaluate the joke asap."
}

Upvote Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

POST
https://api.humorapi.com/jokes/{id}/upvote
Example Request
POST
https://api.humorapi.com/jokes/123/upvote
Response
{
    "message": "Thanks for submitting an upvote."
}

Downvote Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

POST
https://api.humorapi.com/jokes/{id}/downvote
Example Request
POST
https://api.humorapi.com/jokes/123/downvote
Response
{
    "message": "Thanks for submitting a downvote."
}

Search Memes

With over 50,000 jokes, you should find something for any occasion. There are 27 categories to choose from but you can also search for very specific words within jokes.

GET
https://api.humorapi.com/memes/search
Example Request and Response
GET
https://api.humorapi.com/memes/search?number=3&keywords=rocket
{
    "memes": [
        {
            "id": 6696,
            "url": "https://i.imgur.com/1rmAxUG.jpg",
            "type": "image/jpeg"
        },
        {
            "id": 6697,
            "url": "https://i.imgur.com/ELT8zMQ.jpg",
            "type": "image/jpeg"
        },
        {
            "id": 6698,
            "url": "https://i.imgur.com/8JTc5z3.jpg",
            "type": "image/jpeg"
        }
    ],
    "available": 32
}

Random Meme

With over 50,000 jokes, you should find something for any occasion. There are 27 categories to choose from but you can also search for very specific words within jokes.

GET
https://api.humorapi.com/memes/random
Example Request and Response
GET
https://api.humorapi.com/memes/random?keywords=rocket
{
    "id": 50561,
    "url": "https://preview.redd.it/hg0zn2mhjsh01.png?width=640&crop=smart&auto=webp&s=f19b0a87edfc6c71b35ec9aceb64799cd532ff59",
    "type": "image/png"
}

Upvote Meme

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

POST
https://api.humorapi.com/memes/{id}/upvote
Example Request
POST
https://api.humorapi.com/memes/123/upvote
Response
{
    "message": "Thanks for submitting an upvote."
}

Downvote Meme

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

POST
https://api.humorapi.com/memes/{id}/downvote
Example Request
POST
https://api.humorapi.com/memes/123/downvote
Response
{
    "message": "Thanks for submitting a downvote."
}

Search Gifs

With over 50,000 jokes, you should find something for any occasion. There are 27 categories to choose from but you can also search for very specific words within jokes.

GET
https://api.humorapi.com/gif/search
Example Request and Response
GET
https://api.humorapi.com/gif/search?query=dog&number=3
{
    "images": [
        {
            "url": "https://media.tenor.com/images/f97a4505bb4f972cef00bc377aff7f4e/tenor.gif",
            "width": 498,
            "height": 364
        },
        {
            "url": "https://media.tenor.com/images/1d73fd5b39730fd356b482128eb3746a/tenor.gif",
            "width": 498,
            "height": 490
        },
        {
            "url": "https://media.tenor.com/images/6e45dbbc34d8427ffcc322024c73f8fc/tenor.gif",
            "width": 498,
            "height": 498
        }
    ]
}

Praise

With over 50,000 jokes, you should find something for any occasion. There are 27 categories to choose from but you can also search for very specific words within jokes.

GET
https://api.humorapi.com/praise
Example Request and Response
GET
https://api.humorapi.com/praise?name=Alex&reason=you+did+it+again
{
    "text": "Bravo Alex, you mastermind, you did it again."
}

Insult

With over 50,000 jokes, you should find something for any occasion. There are 27 categories to choose from but you can also search for very specific words within jokes.

GET
https://api.humorapi.com/insult
Example Request and Response
GET
https://api.humorapi.com/insult?name=Alex&reason=you+dropped+the+ball
{
    "text": "Holy moley, you dropped the ball Alex, you dingbat."
}

Rate Word

With over 50,000 jokes, you should find something for any occasion. There are 27 categories to choose from but you can also search for very specific words within jokes.

GET
https://api.humorapi.com/words/rate
Example Request and Response
GET
https://api.humorapi.com/words/rate?word=cookie
{
    "rating": 0.57
}

Generate Nonsense Word

With over 50,000 jokes, you should find something for any occasion. There are 27 categories to choose from but you can also search for very specific words within jokes.

GET
https://api.humorapi.com/words/nonsense/random
Example Request and Response
GET
https://api.humorapi.com/words/nonsense/random
{
    "word": "caboo",
    "rating": 0.41
}
  • Clean
  • Animal
  • Food
  • Sexual
  • Knock Knock
  • Sport
  • Blondes
  • Law
  • Nerdy
  • Relationship
  • Deep Thougths
  • Dark
  • One Liner
  • Political
  • Chuck Norris
  • Yo Momma
  • NSFW
  • Religious
  • School
  • Jewish
  • Racist
  • Insults
  • Sexist
  • Holiday
  • Analogy
  • Christmas
  • Kids

Rate Limiting & Quotas

Each API plan comes with a daily quota of points. Every API call you make costs a certain amount of points. Usually, every request is
1 point
and
0.01 points
per result returned, but there are many exceptions. At the bottom of each endpoint description you will find information about the number of points required for that endpoint.

When you are on the free plan and your daily quota is used up, the API will respond with the error code 402 and no more calls can be made until your quota resets.

You have complete control over your quota by looking at your console dashboard and checking the API response headers that appear with every answer from the API. These response headers are:

  • X-API-Quota-Request: The number of points used by the request.
  • X-API-Quota-Used: The number of points used in total today. This number resets to zero at midnight UTC (click here to compare to your local time zone).
  • X-API-Quota-Left: The number of points left today (depends on your plan).

Rate Limiting

There is a limit of how many requests you can make per second. The limits depend on the plan you are on. If you try making more requests you will receive a 429 error.

  • Free: 60 requests in 1 minute
  • Jack: 2 requests per second
  • Jester: 5 requests per second
  • Joker: 10 requests per second

Authentication

To use the API you need an API key. You can get a free one by simply signing up here.

Once you have your API key, you have to put it in the request URL for every request you make like so ?api-key=YOUR-API-KEY.

Attention: Only the first query parameter is prefixed with a ? (question mark), all subsequent ones will be prefixed with a & (ampersand). That is how URLs work and nothing related to our API. Here's a full example with two parameters api-key and include-tags: https://api.humorapi.com/jokes/search?api-key=YOUR-API-KEY&include-tags=tag1,tag2.

Alternatively, you can put the API key in the request header as x-api-key.