canonical: https://jentic.com/apis/jokeapi.dev/jokeapi

# JokeAPI

Jentic publishes the only available OpenAPI specification for JokeAPI, keeping it validated and agent-ready. The JokeAPI serves jokes to AI agents from a free, open catalog across categories such as programming, pun, and spooky. Agents fetch a single joke or several at once, filter by category, language, and content flags, and receive either a single-line joke or a two-part setup and delivery. They can also submit a new joke for review and read the supported categories, languages, flags, and formats. No authentication is required.

## For AI agents

Fetch and filter jokes by category, language, and content flags, and submit new jokes, from a free open catalog. No authentication is required.

## Scope

Does not generate original jokes or moderate submissions automatically. Use for fetching and submitting catalog jokes only.

## Capabilities

- Fetch a single joke or several at once from chosen categories
- Filter jokes by category, language, and content flags
- Get one-line jokes or two-part setup-and-delivery jokes
- List available categories, languages, flags, and formats
- Submit a new joke for review
- Check API availability and read API information

## Use cases

### Agent Joke Retrieval via Jentic

AI agents pull jokes from JokeAPI through Jentic as one discoverable integration. An agent searches by intent, receives the joke operation schema, and fetches a joke filtered by category and content flags end to end. Because the API needs no credential, Jentic simply formats the request and runs it from your own instance, so the agent gets clean content without a manual integration.

Example prompt: Search Jentic for 'get a joke from JokeAPI', load the GET `/joke/{categories}` schema, and fetch a joke filtered by category

### Safe-for-Work Content Filtering

An agent that posts lighthearted content to a workplace channel fetches jokes while excluding categories and content flags that are not appropriate. JokeAPI exposes explicit category and blacklist-flag controls, so the agent can request only clean, on-brand jokes rather than filtering results after the fact.

Example prompt: Call GET `/joke/{categories}` with blacklist flags set, and read GET /flags to see which flags are available

### Community Joke Submission

An agent that collects jokes from users forwards them to JokeAPI's review queue so approved ones join the public catalog. The submit operation lets the agent contribute content back to the community catalog it reads from, closing the loop between gathering and publishing.

Example prompt: Call POST /submit with the joke payload to add a new joke to the review queue

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/joke/{categories}` | Get one or more jokes from the specified categories |
| GET | `/categories` | Get all available joke categories |
| GET | `/languages` | Get all supported languages |
| GET | `/info` | Get API information including version and joke count |
| GET | `/flags` | Get all available blacklist flags |
| POST | `/submit` | Submit a new joke for review |

## Key resources

- **Jokes** — Fetch one or more jokes from chosen categories with filtering
- **Catalog metadata** — List available categories, languages, flags, and response formats
- **Submissions** — Submit a new joke to the review queue

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 61 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 85 / 100
  - Developer Experience & Jentic Compatibility: 58 / 100
  - AI-Readiness & Agent Experience: 38 / 100
  - Agent Usability: 94 / 100
  - Security: 100 / 100
  - AI Discoverability: 54 / 100
- **View full report:** https://jentic.com/apis/jokeapi.dev/jokeapi/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** JokeAPI needs no setup: there is no key to obtain and no account to create. Through Jentic you install once, import JokeAPI from the API Directory, and your agent calls it, with Jentic handling request formatting and category filters.
- **Permission scoping:** Even without a credential, you choose which JokeAPI operations your agent may call, so a rule can allow joke retrieval while withholding the submit-a-joke operation. Submissions or other operations stay out unless you grant them.
- **Credential handling:** JokeAPI needs no credential, so there is nothing to store or inject. Your agent calls it directly through Jentic with no key to manage.
- **Discovery method:** Agents search Jentic by intent such as 'get a programming joke' or 'list joke categories', and Jentic returns the matching JokeAPI operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Jokes One** — Alternative joke API with a large categorized catalog
- **Fun Generators Riddle** — Complementary riddle content for lighthearted interactions
- **PokeAPI** — Complementary free open catalog API for playful content

## FAQ

### Why is there no official OpenAPI spec for JokeAPI?

JokeAPI does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call JokeAPI via structured tooling. It is validated against the live API and kept up to date. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### What authentication does the JokeAPI use?

None. JokeAPI is a free, open API that needs no key or token, so your agent calls it without any credential. Through Jentic, it runs from your own instance like any other integration.

### Can I fetch a joke by category with the JokeAPI?

Yes. Fetch one or more jokes from chosen categories with GET `/joke/{categories}`, and list the available categories with GET /categories.

### How do I get a joke with the JokeAPI through Jentic?

Search Jentic for 'get a joke from JokeAPI', load the returned GET `/joke/{categories}` operation with its input schema, and your agent fetches the joke, filtering by category and content flags as needed.

### Is there a JokeAPI MCP server?

You don't need an MCP server to give your agent the JokeAPI. Jentic connects it directly from the API Directory: import it and your agent calls it, discovering operations on demand instead of loading a separate server's tool definitions into its context.

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

Yes. Even though JokeAPI needs no credential, you still choose which operations your agent may call, so you can allow joke retrieval while withholding the submit-a-joke operation. Scoping is by operation, so the agent reaches only the endpoints you approve.