canonical: https://jentic.com/apis/jokes.one/jokes-one

# Jokes One API

Jokes One is a content service that publishes a curated catalogue of jokes, including a daily Joke of the Day and a searchable archive across multiple categories. The API exposes endpoints for fetching the joke of the day, searching by keyword or category, retrieving random jokes, and (for subscribers) managing joke entries and tags. It is the right pick for content apps, chatbots, or marketing tools that want a lightweight humour feed without curating their own corpus.

## For AI agents

Fetch the daily Joke of the Day, search and pull random jokes by category or keyword, and (for subscribers) manage joke entries and tags so agents can drop a joke into chat, email, or a UI surface.

## Scope

Does not handle text-to-speech delivery, content moderation by user, or licensing for commercial republishing - use for joke retrieval, search, and subscriber-side joke management only.

## Capabilities

- Fetch the current Joke of the Day or filter it by category
- List jokes from the catalogue with category and keyword filters
- Pull a single random joke for chatbot or daily-message use
- Search jokes by free-text keyword or by category metadata
- Add or remove tags on a joke entry as a subscriber operation
- Create, update, or delete joke records using the subscriber endpoints

## Use cases

### Daily-joke Slack bot

Workplace bots that post a daily light-hearted message can pull the Joke of the Day each morning and post it into a designated channel. GET /jod returns a single curated joke with category metadata, so the bot can format the message and choose an appropriate channel. The simple GET-only flow makes this a 10-minute integration for any chat bot.

Example prompt: Call GET /jod each weekday at 9:00, format the response title and body, and post it to the #general Slack channel

### Chatbot small-talk filler

Conversational agents handling customer support or onboarding can lean on a random-joke endpoint to lighten queues and humanise small-talk moments. GET `/joke/random` returns a single joke per call with no parameters required. Categorical filters can keep the humour aligned with the product's brand voice.

Example prompt: Call GET `/joke/random` with category=clean to fetch a random joke and inject it into the chatbot's small-talk response slot

### Themed content widget

Editorial sites or apps with topical content (e.g., a coffee blog, a sports site) can run keyword-driven joke widgets that pull a few jokes matching the page topic. GET `/joke/search` with a keyword returns a list which the front-end can rotate. Combined with category metadata, this surfaces relevant jokes alongside the main content without manual curation.

Example prompt: Call GET `/joke/search`?query=coffee to list matching jokes, then render the top three in the page's sidebar widget

### Agent-driven daily humour via Jentic

An AI assistant configured to brighten user check-ins can call jokes.one through Jentic without requiring its own API key. The agent expresses intent ('tell me a joke'), Jentic resolves to GET `/joke/random`, injects the X-JokesOne-API-Secret header from the vault, and returns the joke text. This keeps the subscriber key out of agent prompts and lets one credential serve many agent flows.

Example prompt: Use Jentic to search 'get a random joke', load GET `/joke/random`, and execute it to return a clean joke for the user's check-in

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/jod` | Get the Joke of the Day |
| GET | `/jod/categories` | List Joke of the Day categories |
| GET | `/joke/random` | Get a random joke |
| GET | `/joke/search` | Search jokes by keyword |
| GET | `/joke/list` | List jokes from the catalogue |
| GET | `/joke/categories/search` | Search jokes by category |
| POST | `/joke/tags/add` | Add tags to a joke (subscriber) |
| POST | `/joke/tags/remove` | Remove tags from a joke (subscriber) |

## Key resources

- **Joke of the Day** — Single curated daily joke and category list
- **Jokes** — Search, list, and random-pull jokes from the catalogue
- **Joke Management** — Subscriber-only create, update, delete, and tag operations

## Why Jentic

- **Setup:** Wiring the Jokes One API by hand means learning its secret-key request header, building query parameters for the joke and category endpoints, and parsing the responses yourself. Through Jentic you install once, import the Jokes One API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** This API's read and search endpoints (`/joke/random`, `/joke/search`, /jod) address jokes by query rather than by a resource id in the path, so you limit the agent to the operations it needs, such as fetching the daily joke or searching jokes. Tag-editing operations like adding or removing tags are left out unless you include them.
- **Credential handling:** Your Jokes One API secret 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 'tell a joke' or 'daily joke', and Jentic returns the matching Jokes One operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Humor API** — Larger humour API with jokes, memes, and ratings beyond the jokes.one catalogue
- **API Ninjas APIs** — Multi-purpose utility API collection that includes a free jokes endpoint
- **Slack API** — Post the joke fetched from Jokes One into a Slack channel or DM

## FAQ

### What authentication does the Jokes One API use?

The Jokes One API uses an API key passed in the X-JokesOne-API-Secret header. Public endpoints like GET /jod are usable anonymously; the subscriber endpoints (joke management and tag operations) require a valid key. Jentic stores the key encrypted and injects it on each request.

### Can I get the Joke of the Day for free?

GET /jod is the public Joke of the Day endpoint and is callable without a subscription. GET `/jod/categories` returns the available daily categories, so you can request a specific theme if the day's catalogue supports it.

### What are the rate limits for the Jokes One API?

Rate limits are tied to subscription tier on jokes.one - the spec does not publish numeric limits. Treat the API as low-volume for free use; check the dashboard at jokes.one/api/joke/ for paid-tier throughput.

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

Search Jentic for 'get a random joke', load GET `/joke/random`, and execute it. Jentic returns the joke title and body, and the X-JokesOne-API-Secret header is injected automatically. Get started with Jentic One, the self-hosted execution layer.

### Can I add or remove tags on a joke?

Yes, but only for subscribers. POST `/joke/tags/add` and POST `/joke/tags/remove` modify the tag set on a joke entry. These endpoints reject unauthenticated requests, so the API key must be present.

### How do I search jokes by category?

Use GET `/joke/categories/search` with a category name to pull jokes filtered by that taxonomy entry. For free-text search across joke bodies, use GET `/joke/search` with a query parameter instead.

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

Yes. Because Jentic One is self-hosted, your own rules decide which Jokes One operations and credentials the agent can use, so you can grant only the read and search calls it needs, such as GET /jod for the Joke of the Day, GET `/joke/random`, and GET `/joke/search.` The subscriber tag-editing operations, POST `/joke/tags/add` and POST `/joke/tags/remove`, stay unavailable to the agent unless you explicitly include them. Your Jokes One API secret is held by your own instance and injected only on the calls you allow, so it never reaches the agent's prompt.