openapi: 3.0.3
info:
  title: Joke Jokes Metadata 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: Metadata
  description: Operations describing the API surface — categories, flags, formats, languages.
paths:
  /categories:
    get:
      operationId: getCategories
      summary: JokeAPI List Categories
      description: List every joke category JokeAPI exposes, plus the recognised category aliases. Use one of the returned categories as the path parameter to `/joke/{category}`.
      tags:
      - Metadata
      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: Categories envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponse'
              examples:
                GetCategories200Example:
                  summary: Default getCategories 200 response
                  x-microcks-default: true
                  value:
                    error: false
                    categories:
                    - Any
                    - Misc
                    - Programming
                    - Dark
                    - Pun
                    - Spooky
                    - Christmas
                    categoryAliases:
                    - alias: Coding
                      resolved: Programming
                    - alias: Development
                      resolved: Programming
                    - alias: Halloween
                      resolved: Spooky
                    timestamp: 1780051223357
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /flags:
    get:
      operationId: getFlags
      summary: JokeAPI List Blacklist Flags
      description: List the blacklist flags consumers can pass to `?blacklistFlags`. Each flag indicates a category of potentially offensive content.
      tags:
      - Metadata
      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: Flags envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagsResponse'
              examples:
                GetFlags200Example:
                  summary: Default getFlags 200 response
                  x-microcks-default: true
                  value:
                    error: false
                    flags:
                    - nsfw
                    - religious
                    - political
                    - racist
                    - sexist
                    - explicit
                    timestamp: 1780051223357
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /formats:
    get:
      operationId: getFormats
      summary: JokeAPI List Response Formats
      description: List the response formats JokeAPI can return. Values map to the `?format` query parameter on every other endpoint.
      tags:
      - Metadata
      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: Formats envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormatsResponse'
              examples:
                GetFormats200Example:
                  summary: Default getFormats 200 response
                  x-microcks-default: true
                  value:
                    error: false
                    formats:
                    - json
                    - xml
                    - yaml
                    - txt
                    timestamp: 1780051223357
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /languages:
    get:
      operationId: getLanguages
      summary: JokeAPI List Supported Languages
      description: List the joke languages and the system languages JokeAPI supports. Joke languages have at least one joke available; system languages affect error-message localisation.
      tags:
      - Metadata
      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: Languages envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguagesResponse'
              examples:
                GetLanguages200Example:
                  summary: Default getLanguages 200 response
                  x-microcks-default: true
                  value:
                    error: false
                    defaultLanguage: en
                    jokeLanguages:
                    - cs
                    - de
                    - en
                    - es
                    - fr
                    - pt
                    systemLanguages:
                    - cs
                    - de
                    - en
                    - es
                    - pt
                    possibleLanguages:
                    - code: en
                      name: English
                    - code: de
                      name: German
                    - code: fr
                      name: French
                    timestamp: 1780051223357
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /langcode/{language}:
    get:
      operationId: getLangcode
      summary: JokeAPI Resolve Language Code
      description: Resolve a human-readable language name (e.g. `german`) to its ISO 639-1 language code (e.g. `de`).
      tags:
      - Metadata
      parameters:
      - name: language
        in: path
        required: true
        description: Human-readable language name in English.
        schema:
          type: string
        example: german
      - 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: Language code envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LangcodeResponse'
              examples:
                GetLangcode200Example:
                  summary: Default getLangcode 200 response
                  x-microcks-default: true
                  value:
                    error: false
                    code: de
                    timestamp: 1780051223357
        '404':
          description: Unknown language name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JokeError'
              examples:
                GetLangcode404Example:
                  summary: Default getLangcode 404 response
                  x-microcks-default: true
                  value:
                    error: true
                    internalError: false
                    code: 104
                    message: Language not supported
                    causedBy:
                    - No mapping found for that language name.
                    timestamp: 1780051223357
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    CategoriesResponse:
      type: object
      description: Categories metadata envelope.
      properties:
        error:
          type: boolean
          example: false
        categories:
          type: array
          description: Canonical category names accepted by `/joke/{category}`.
          items:
            type: string
          example:
          - Any
          - Misc
          - Programming
          - Dark
          - Pun
          - Spooky
          - Christmas
        categoryAliases:
          type: array
          description: Aliases that resolve to a canonical category.
          items:
            type: object
            properties:
              alias:
                type: string
                example: Coding
              resolved:
                type: string
                example: Programming
        timestamp:
          type: integer
          description: Server-side Unix epoch timestamp in milliseconds.
          example: 1780051223357
      required:
      - error
      - categories
      - timestamp
    FlagsResponse:
      type: object
      description: Blacklist flags metadata envelope.
      properties:
        error:
          type: boolean
          example: false
        flags:
          type: array
          description: Flags consumers can pass to `?blacklistFlags`.
          items:
            type: string
          example:
          - nsfw
          - religious
          - political
          - racist
          - sexist
          - explicit
        timestamp:
          type: integer
          example: 1780051223357
      required:
      - error
      - flags
      - timestamp
    JokeError:
      type: object
      description: Error envelope returned for any failed request.
      properties:
        error:
          type: boolean
          example: true
        internalError:
          type: boolean
          description: True when the failure originated server-side rather than from input.
          example: false
        code:
          type: integer
          description: JokeAPI internal error code.
          example: 106
        message:
          type: string
          description: Short error label.
          example: No matching joke found
        causedBy:
          type: array
          description: Human-readable reasons the request failed.
          items:
            type: string
          example:
          - No jokes were found that match your provided filter(s).
        additionalInfo:
          type: string
          description: Optional hint to help the consumer correct the request.
          example: Try removing the safe-mode or blacklistFlags filters.
        timestamp:
          type: integer
          description: Server-side Unix epoch timestamp in milliseconds.
          example: 1780051223357
      required:
      - error
      - code
      - message
      - causedBy
      - timestamp
    LanguagesResponse:
      type: object
      description: Language metadata envelope.
      properties:
        error:
          type: boolean
          example: false
        defaultLanguage:
          type: string
          description: ISO 639-1 default language.
          example: en
        jokeLanguages:
          type: array
          description: Languages that have at least one joke.
          items:
            type: string
          example:
          - cs
          - de
          - en
          - es
          - fr
          - pt
        systemLanguages:
          type: array
          description: Languages JokeAPI uses for system messages and errors.
          items:
            type: string
          example:
          - cs
          - de
          - en
          - es
          - pt
        possibleLanguages:
          type: array
          description: Full set of ISO codes JokeAPI recognises.
          items:
            type: object
            properties:
              code:
                type: string
                example: en
              name:
                type: string
                example: English
        timestamp:
          type: integer
          example: 1780051223357
      required:
      - error
      - defaultLanguage
      - jokeLanguages
      - systemLanguages
      - timestamp
    FormatsResponse:
      type: object
      description: Response-format metadata envelope.
      properties:
        error:
          type: boolean
          example: false
        formats:
          type: array
          description: Response formats accepted by `?format`.
          items:
            type: string
          example:
          - json
          - xml
          - yaml
          - txt
        timestamp:
          type: integer
          example: 1780051223357
      required:
      - error
      - formats
      - timestamp
    LangcodeResponse:
      type: object
      description: Language-code resolution envelope.
      properties:
        error:
          type: boolean
          example: false
        code:
          type: string
          description: Resolved ISO 639-1 language code.
          example: de
        timestamp:
          type: integer
          example: 1780051223357
      required:
      - error
      - code
      - timestamp