openapi: 3.0.3
info:
  title: Joke Jokes 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: Jokes
  description: Operations for retrieving and submitting jokes.
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
  /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
    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
    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
    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
    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
    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
    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