openapi: 3.0.3 info: title: Joke Jokes System API description: JokeAPI is a free and open REST API that delivers consistently formatted jokes in JSON, XML, YAML, or plain text. Powerful filters let consumers narrow jokes by category, language, content flags, type, ID range, or full-text contains search, with optional safe-mode to exclude any joke that carries a blacklist flag. The API requires no sign-up, supports CORS, and is rate-limited per IP. Open source under the MIT license, maintained by Sv443. version: 2.3.3 contact: name: Sv443 url: https://sv443.net/ license: name: MIT url: https://github.com/Sv443-Network/JokeAPI/blob/main/LICENSE.txt x-generated-from: documentation x-last-validated: '2026-05-29' servers: - url: https://v2.jokeapi.dev description: Primary public endpoint - url: https://sv443.net/jokeapi/v2 description: Legacy alias for the primary endpoint tags: - name: System description: Health and discovery endpoints. paths: /info: get: operationId: getInfo summary: JokeAPI Get Info description: Return runtime metadata about JokeAPI — version, total joke count, the full list of categories, flags, types, supported formats, language counts, per-language ID ranges, and per-language safe-joke counts. tags: - System parameters: - name: format in: query required: false description: Response format. Defaults to `json`. schema: type: string enum: - json - xml - yaml - txt default: json example: json - name: lang in: query required: false description: ISO 639-1 system language for the response messages. schema: type: string default: en example: en responses: '200': description: Runtime info envelope. content: application/json: schema: $ref: '#/components/schemas/InfoResponse' examples: GetInfo200Example: summary: Default getInfo 200 response x-microcks-default: true value: error: false version: 2.3.3 jokes: totalCount: 1368 categories: - Any - Misc - Programming - Dark - Pun - Spooky - Christmas flags: - nsfw - religious - political - racist - sexist - explicit types: - single - twopart submissionURL: https://v2.jokeapi.dev#submit idRange: en: - 0 - 318 de: - 0 - 35 safeJokes: - lang: en count: 183 - lang: de count: 29 formats: - json - xml - yaml - txt jokeLanguages: 6 systemLanguages: 5 info: If you want to stay up to date on the status and future updates of JokeAPI, consider joining the Discord server. timestamp: 1780051223357 x-microcks-operation: delay: 0 dispatcher: FALLBACK /endpoints: get: operationId: getEndpoints summary: JokeAPI List Endpoints description: List every documented endpoint exposed by JokeAPI, including its URL, usage notes, and supported response formats. tags: - System parameters: - name: format in: query required: false description: Response format. Defaults to `json`. schema: type: string enum: - json - xml - yaml - txt default: json example: json responses: '200': description: Endpoints envelope. content: application/json: schema: $ref: '#/components/schemas/EndpointsResponse' examples: GetEndpoints200Example: summary: Default getEndpoints 200 response x-microcks-default: true value: error: false endpoints: - name: Joke usage: method: GET url: https://v2.jokeapi.dev/joke/{category} supportedParams: - format - blacklistFlags - type - contains - idRange - amount - lang - safe-mode timestamp: 1780051223357 x-microcks-operation: delay: 0 dispatcher: FALLBACK /ping: get: operationId: ping summary: JokeAPI Ping description: Lightweight uptime endpoint. Returns a short payload confirming the API is reachable and reporting the server timestamp. tags: - System parameters: - name: format in: query required: false description: Response format. Defaults to `json`. schema: type: string enum: - json - xml - yaml - txt default: json example: json responses: '200': description: Ping envelope. content: application/json: schema: $ref: '#/components/schemas/PingResponse' examples: Ping200Example: summary: Default ping 200 response x-microcks-default: true value: error: false ping: Pong! timestamp: 1780051223357 x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: EndpointsResponse: type: object description: Endpoint catalogue envelope. properties: error: type: boolean example: false endpoints: type: array items: type: object properties: name: type: string example: Joke usage: type: object properties: method: type: string example: GET url: type: string example: https://v2.jokeapi.dev/joke/{category} supportedParams: type: array items: type: string example: - format - blacklistFlags - type - contains - idRange - amount - lang - safe-mode timestamp: type: integer example: 1780051223357 required: - error - endpoints - timestamp PingResponse: type: object description: Ping envelope. properties: error: type: boolean example: false ping: type: string example: Pong! timestamp: type: integer example: 1780051223357 required: - error - ping - timestamp InfoResponse: type: object description: Runtime info envelope describing JokeAPI's current state. properties: error: type: boolean example: false version: type: string description: Running JokeAPI version. example: 2.3.3 jokes: type: object description: Joke catalogue snapshot. properties: totalCount: type: integer example: 1368 categories: type: array items: type: string example: - Any - Misc - Programming - Dark - Pun - Spooky - Christmas flags: type: array items: type: string example: - nsfw - religious - political - racist - sexist - explicit types: type: array items: type: string example: - single - twopart submissionURL: type: string example: https://v2.jokeapi.dev#submit idRange: type: object description: Per-language ID range pair `[min, max]`. additionalProperties: type: array items: type: integer minItems: 2 maxItems: 2 safeJokes: type: array items: type: object properties: lang: type: string count: type: integer formats: type: array items: type: string example: - json - xml - yaml - txt jokeLanguages: type: integer example: 6 systemLanguages: type: integer example: 5 info: type: string example: If you want to stay up to date on the status and future updates of JokeAPI... timestamp: type: integer example: 1780051223357 required: - error - version - jokes - formats - timestamp