openapi: 3.0.3
info:
  title: JokeAPI
  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: Jokes
  description: Operations for retrieving and submitting jokes.
- name: Metadata
  description: Operations describing the API surface — categories, flags, formats, languages.
- name: System
  description: Health and discovery endpoints.
paths:
  /joke/{category}:
    get:
      operationId: getJoke
      summary: JokeAPI Get Joke by Category
      description: >-
        Retrieve one or more jokes from a single category, a comma-separated
        list of categories, or the special value `Any`. Supports filtering by
        blacklist flags, joke type, language, ID range, contains-text search,
        amount, and safe-mode.
      tags:
      - Jokes
      parameters:
      - name: category
        in: path
        required: true
        description: >-
          Category or comma-separated list of categories. Use `Any` to draw
          from all categories.
        schema:
          type: string
          enum:
          - Any
          - Misc
          - Programming
          - Dark
          - Pun
          - Spooky
          - Christmas
        example: Programming
      - 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 language code for the joke language. Supported jokes
          languages include `en`, `de`, `cs`, `es`, `fr`, `pt`. Defaults to `en`.
        schema:
          type: string
          default: en
        example: en
      - name: blacklistFlags
        in: query
        required: false
        description: >-
          Comma-separated list of flags to exclude (`nsfw`, `religious`,
          `political`, `racist`, `sexist`, `explicit`). Any joke carrying at
          least one listed flag is filtered out.
        schema:
          type: string
        example: nsfw,racist,sexist
      - name: type
        in: query
        required: false
        description: Restrict results to a single joke type.
        schema:
          type: string
          enum: [single, twopart]
        example: twopart
      - name: contains
        in: query
        required: false
        description: >-
          URL-encoded substring that must appear in the joke text (or the
          setup/delivery of a twopart joke).
        schema:
          type: string
        example: developer
      - name: idRange
        in: query
        required: false
        description: >-
          Inclusive ID range (e.g. `0-50`) or a single ID (e.g. `42`) to
          constrain results.
        schema:
          type: string
        example: 0-50
      - name: amount
        in: query
        required: false
        description: Number of jokes to retrieve (1-10). Defaults to 1.
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 1
        example: 1
      - name: safe-mode
        in: query
        required: false
        description: >-
          When present (no value required), exclude any joke that carries any
          flag and any joke categorised as Dark.
        schema:
          type: string
        example: ""
      responses:
        '200':
          description: A single joke, an envelope of multiple jokes, or an error envelope.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SingleJoke'
                - $ref: '#/components/schemas/TwopartJoke'
                - $ref: '#/components/schemas/JokeBatch'
                - $ref: '#/components/schemas/JokeError'
              examples:
                GetJoke200Example:
                  summary: Default getJoke 200 response
                  x-microcks-default: true
                  value:
                    error: false
                    category: Programming
                    type: twopart
                    setup: Why don't programmers like nature?
                    delivery: It has too many bugs.
                    flags:
                      nsfw: false
                      religious: false
                      political: false
                      racist: false
                      sexist: false
                      explicit: false
                    id: 127
                    safe: true
                    lang: en
            application/xml:
              schema:
                type: string
            application/x-yaml:
              schema:
                type: string
            text/plain:
              schema:
                type: string
        '400':
          description: Malformed request (e.g. unknown category or invalid parameter).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JokeError'
              examples:
                GetJoke400Example:
                  summary: Default getJoke 400 response
                  x-microcks-default: true
                  value:
                    error: true
                    internalError: false
                    code: 106
                    message: No matching joke found
                    causedBy:
                    - No jokes were found that match your provided filter(s).
                    additionalInfo: Try removing the safe-mode or blacklistFlags filters.
                    timestamp: 1780051223357
        '404':
          description: No joke matches the given filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JokeError'
              examples:
                GetJoke404Example:
                  summary: Default getJoke 404 response
                  x-microcks-default: true
                  value:
                    error: true
                    internalError: false
                    code: 106
                    message: No matching joke found
                    causedBy:
                    - No jokes were found that match your provided filter(s).
                    additionalInfo: Try removing the safe-mode or blacklistFlags filters.
                    timestamp: 1780051223357
        '429':
          description: Rate-limit exceeded (120 requests per minute per IP).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JokeError'
              examples:
                GetJoke429Example:
                  summary: Default getJoke 429 response
                  x-microcks-default: true
                  value:
                    error: true
                    internalError: false
                    code: 101
                    message: Rate limit exceeded
                    causedBy:
                    - You exceeded 120 requests per minute.
                    additionalInfo: Wait until the Retry-After window expires.
                    timestamp: 1780051223357
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
  /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
  /submit:
    post:
      operationId: submitJoke
      summary: JokeAPI Submit Joke
      description: >-
        Submit a joke for moderator review. Submissions are rate-limited
        separately at 5 per minute per IP. Pass `?dry-run` to validate the
        payload structure without persisting the submission.
      tags:
      - Jokes
      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: dry-run
        in: query
        required: false
        description: >-
          When present, the submission is validated for shape but not
          persisted. No value is required.
        schema:
          type: string
        example: ""
      requestBody:
        required: true
        description: Joke submission payload (single or twopart).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JokeSubmission'
            examples:
              SubmitJokeRequestExample:
                summary: Default submitJoke request
                x-microcks-default: true
                value:
                  formatVersion: 3
                  category: Programming
                  type: twopart
                  setup: Why don't programmers like nature?
                  delivery: It has too many bugs.
                  flags:
                    nsfw: false
                    religious: false
                    political: false
                    racist: false
                    sexist: false
                    explicit: false
                  lang: en
      responses:
        '201':
          description: Submission accepted (or validated successfully in dry-run mode).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionResponse'
              examples:
                SubmitJoke201Example:
                  summary: Default submitJoke 201 response
                  x-microcks-default: true
                  value:
                    error: false
                    message: Joke submission was successful.
                    submission:
                      formatVersion: 3
                      category: Programming
                      type: twopart
                      setup: Why don't programmers like nature?
                      delivery: It has too many bugs.
                      flags:
                        nsfw: false
                        religious: false
                        political: false
                        racist: false
                        sexist: false
                        explicit: false
                      lang: en
                    timestamp: 1780051223357
        '400':
          description: Submission failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JokeError'
              examples:
                SubmitJoke400Example:
                  summary: Default submitJoke 400 response
                  x-microcks-default: true
                  value:
                    error: true
                    internalError: false
                    code: 105
                    message: Submission malformed
                    causedBy:
                    - The provided payload does not match the expected JokeSubmission schema.
                    timestamp: 1780051223357
        '429':
          description: Submission rate-limit exceeded (5 per minute per IP).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JokeError'
              examples:
                SubmitJoke429Example:
                  summary: Default submitJoke 429 response
                  x-microcks-default: true
                  value:
                    error: true
                    internalError: false
                    code: 101
                    message: Submission rate limit exceeded
                    causedBy:
                    - You exceeded 5 submissions per minute.
                    timestamp: 1780051223357
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    JokeFlags:
      type: object
      description: Content classification flags carried on every joke.
      properties:
        nsfw:
          type: boolean
          description: Joke contains adult or explicit sexual content.
          example: false
        religious:
          type: boolean
          description: Joke references or mocks religion.
          example: false
        political:
          type: boolean
          description: Joke references politics or political figures.
          example: false
        racist:
          type: boolean
          description: Joke contains racist content.
          example: false
        sexist:
          type: boolean
          description: Joke contains sexist content.
          example: false
        explicit:
          type: boolean
          description: Joke contains explicit language unrelated to NSFW.
          example: false
      required: [nsfw, religious, political, racist, sexist, explicit]
    SingleJoke:
      type: object
      description: A joke delivered as one line of text.
      properties:
        error:
          type: boolean
          description: Always false on a successful joke response.
          example: false
        category:
          type: string
          description: Category the joke belongs to.
          enum: [Misc, Programming, Dark, Pun, Spooky, Christmas]
          example: Programming
        type:
          type: string
          description: Joke shape — always `single` for this schema.
          enum: [single]
          example: single
        joke:
          type: string
          description: The joke text.
          example: "Why do programmers prefer dark mode? Because light attracts bugs."
        flags:
          $ref: '#/components/schemas/JokeFlags'
        id:
          type: integer
          description: Joke identifier within its language scope.
          example: 42
        safe:
          type: boolean
          description: True when the joke has no flags and is not Dark.
          example: true
        lang:
          type: string
          description: ISO 639-1 language code of the joke.
          example: en
      required: [error, category, type, joke, flags, id, safe, lang]
    TwopartJoke:
      type: object
      description: A joke delivered as a setup/delivery pair.
      properties:
        error:
          type: boolean
          description: Always false on a successful joke response.
          example: false
        category:
          type: string
          description: Category the joke belongs to.
          enum: [Misc, Programming, Dark, Pun, Spooky, Christmas]
          example: Programming
        type:
          type: string
          description: Joke shape — always `twopart` for this schema.
          enum: [twopart]
          example: twopart
        setup:
          type: string
          description: Setup line of the joke.
          example: "Why don't programmers like nature?"
        delivery:
          type: string
          description: Punchline of the joke.
          example: "It has too many bugs."
        flags:
          $ref: '#/components/schemas/JokeFlags'
        id:
          type: integer
          description: Joke identifier within its language scope.
          example: 127
        safe:
          type: boolean
          description: True when the joke has no flags and is not Dark.
          example: true
        lang:
          type: string
          description: ISO 639-1 language code of the joke.
          example: en
      required: [error, category, type, setup, delivery, flags, id, safe, lang]
    JokeBatch:
      type: object
      description: Envelope returned when `?amount` is greater than 1.
      properties:
        error:
          type: boolean
          example: false
        amount:
          type: integer
          description: Number of jokes in this batch.
          example: 3
        jokes:
          type: array
          description: Heterogeneous list of single and twopart jokes.
          items:
            oneOf:
            - $ref: '#/components/schemas/SingleJoke'
            - $ref: '#/components/schemas/TwopartJoke'
      required: [error, amount, jokes]
    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]
    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]
    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]
    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]
    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]
    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]
    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]
    JokeSubmission:
      type: object
      description: Submission payload for `POST /submit`.
      properties:
        formatVersion:
          type: integer
          description: Submission format version. Currently `3`.
          example: 3
        category:
          type: string
          description: Target category for the joke.
          enum: [Misc, Programming, Dark, Pun, Spooky, Christmas]
          example: Programming
        type:
          type: string
          description: Joke shape.
          enum: [single, twopart]
          example: twopart
        joke:
          type: string
          description: Joke text (required when `type` is `single`).
          example: "Why do programmers prefer dark mode? Because light attracts bugs."
        setup:
          type: string
          description: Setup line (required when `type` is `twopart`).
          example: "Why don't programmers like nature?"
        delivery:
          type: string
          description: Punchline (required when `type` is `twopart`).
          example: "It has too many bugs."
        flags:
          $ref: '#/components/schemas/JokeFlags'
        lang:
          type: string
          description: ISO 639-1 language code of the joke.
          example: en
      required: [formatVersion, category, type, flags, lang]
    SubmissionResponse:
      type: object
      description: Submission response envelope.
      properties:
        error:
          type: boolean
          example: false
        message:
          type: string
          example: "Joke submission was successful."
        submission:
          $ref: '#/components/schemas/JokeSubmission'
        timestamp:
          type: integer
          example: 1780051223357
      required: [error, message, timestamp]