canonical: https://jentic.com/apis/humorapi.com/humorapi-main

# Humor API

Jentic publishes the only available OpenAPI specification for Humor API, keeping it validated and agent-ready. Humor API delivers programmatic access to a curated catalogue of jokes, memes, and animated GIFs, plus generative endpoints for praise, insults, and nonsense words. It exposes 16 endpoints covering joke search and retrieval by tags or keywords, meme and GIF lookup, joke voting, joke analysis with sentiment and category scoring, and word funniness rating. Authentication is performed with an api-key passed as a query parameter on every request.

## For AI agents

Search jokes, memes, and GIFs, generate insults or praise, and rate the funniness of words for chat, content, and entertainment agents.

## Scope

Does not handle long-form comedy writing, video clips, or live stand-up booking - use for short-form jokes, memes, GIFs, and generative humour text only.

## Capabilities

- Search jokes by keyword, tag, or content rating across the Humor API catalogue
- Retrieve a random joke or meme filtered by category, language, or maximum length
- Generate a personalised praise or insult line addressed to a named recipient
- Score how funny an arbitrary word is and return a numeric funniness rating
- Submit user-created jokes and cast upvotes or downvotes on existing jokes and memes
- Analyse a joke string for sentiment, type, and category metadata

## Use cases

### Conversational Chatbot Humour

Inject jokes, memes, and witty replies into a chatbot or virtual assistant by querying Humor API for content matched to user keywords or topics. The `/jokes/search` and `/jokes/random` endpoints support filtering by tag, exclude-tag, content rating, and length so the bot only surfaces appropriate material. Integration takes under an hour through Jentic and adds a steady stream of fresh content without curation overhead.

Example prompt: Call `/jokes/random` with include-tags=clean and max-length=200 and return the joke text to the user.

### Social Content Scheduling

Power a content scheduler that posts daily memes or one-liners by pulling random items from `/memes/random` or `/jokes/random` and routing them to social platforms. Filters on keywords, rating, and language let teams keep brand voice consistent. Combined with a posting API like Buffer or a Twitter client, the workflow can be fully automated through Jentic-mediated calls.

Example prompt: Fetch one `/memes/random` with keywords=monday and post the returned image URL to a scheduled tweet.

### Word and Joke Analysis Tooling

Build internal tooling for comedy writers, copywriters, or game designers that scores the funniness of candidate words via `/words/rate` and analyses joke drafts via `/jokes/analyze` for sentiment and category. Useful for A/B testing taglines or grading user submissions in a humour app. Each call returns structured numeric scores rather than free text.

Example prompt: Send the candidate tagline to `/jokes/analyze` and return the sentiment and category fields to the user.

### AI Agent Entertainment Plugin

Give an AI agent a callable tool for entertainment and small-talk responses without baking jokes into the prompt. Through Jentic the agent searches for the operation 'find a random joke', loads the input schema, and executes against `/jokes/random` with parameters chosen at runtime. The api-key never enters the agent context and the agent receives only the structured response payload.

Example prompt: Search Jentic for 'tell a random joke', load the Humor API random joke schema, and execute with include-tags=clean.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/jokes/search` | Search jokes by keyword and tag filters |
| GET | `/jokes/random` | Retrieve a random joke matching filters |
| GET | `/memes/random` | Retrieve a random meme matching filters |
| GET | `/gif/search` | Search animated GIFs by keyword |
| GET | `/praise` | Generate a praise line for a named recipient |
| GET | `/insult` | Generate an insult line for a named recipient |
| GET | `/words/rate` | Return a funniness rating for a word |
| POST | `/jokes/analyze` | Analyse a joke for sentiment and category |

## Key resources

- **Jokes** — Search, random retrieval, voting, submission, and analysis of jokes
- **Memes** — Search and random retrieval of memes with voting endpoints
- **GIFs** — Keyword search across an animated GIF catalogue
- **Praise and Insults** — Generative endpoints that produce a praise or insult line for a named target
- **Word Tools** — Funniness rating and nonsense word generation

## Why Jentic

- **Setup:** Wiring the Humor API by hand means holding an API key, targeting api.humorapi.com, and passing the key as a query parameter on every joke, meme, and GIF call yourself. Through Jentic you install once, import the Humor API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** This API serves content through fixed endpoints with the query in the request parameters (`/jokes/search`, `/memes/random`), so limit the agent to the operations it needs, such as fetching a random joke or searching GIFs. You choose the operations it may call, so joke analysis is not included unless you add it.
- **Credential handling:** Your Humor API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find a random joke' or 'search for a meme', and Jentic returns the matching Humor API operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **GIPHY API** — GIPHY focuses purely on animated GIFs and stickers with a much larger catalogue than Humor API's GIF endpoint
- **Advice Slip API** — Advice Slip returns short pieces of advice, useful alongside Humor API for varied conversational filler
- **Tenor GIF API** — Tenor provides a large GIF library that pairs well with Humor API jokes for richer chatbot replies

## FAQ

### Why is there no official OpenAPI spec for Humor API?

Humor API does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Humor API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Humor API use?

The Humor API uses an API key passed as the api-key query parameter on every request. Through Jentic the key is stored in the credential vault and never enters the agent context - the agent receives a scoped reference and Jentic injects the key at execution time.

### Can I generate a personalised insult or praise line with the Humor API?

Yes. The /insult and /praise endpoints accept a name parameter and return a single generated line addressed to that recipient. They are GET endpoints so they fit cleanly into chatbot reply flows and require only the api-key query parameter.

### What are the rate limits for the Humor API?

The OpenAPI spec does not declare numeric rate limits. Humor API tiers its rate limits by paid plan on the vendor dashboard, so check your plan at humorapi.com for the exact requests-per-day allowance before scaling agent traffic.

### How do I get a random meme through Jentic?

Search Jentic for 'get a random meme', load the schema for the Humor API `/memes/random` operation, and execute with optional keywords, media-type, and min-rating parameters. Install with pip install jentic and call the async search, load, and execute methods to run the request.

### Can I score how funny a word is with the Humor API?

Yes. The `/words/rate` endpoint accepts a single word and returns a numeric funniness rating. It is useful for ranking candidate names, taglines, or game words and runs as a simple GET call with the api-key query parameter.

### Can I limit what my agent is allowed to do with the Humor API?

Yes. Because you run your own self-hosted Jentic One instance, your rules decide which Humor API operations the agent can reach, so you can allow only what it needs, such as fetching a random joke from `/jokes/random` or searching GIFs through `/gif/search.` Operations you do not grant, like joke analysis on `/jokes/analyze` or the /insult and /praise generators, stay out of the agent's reach unless you add them. Your Humor API key is held by your own instance and injected at call time, so scoping the operation list also controls exactly how that credential gets used.