openapi: 3.0.3
info:
  title: Bored Activities Riddles API
  version: 2.0.0
  summary: A Free and Simple API to Help You Find Something Better to Do
  description: The Bored API is a free, no-authentication public API that returns suggestions for things to do when you are bored. The canonical implementation is the open-source MEVN (MongoDB / Express / Vue / Node) project maintained by Drew Thoennes at github.com/drewthoennes/Bored-API. The historically hosted instance at https://www.boredapi.com/ has been intermittently or fully unreachable since 2024 (originally hosted on Heroku); community mirrors such as https://bored-api.appbrewery.com continue to serve the dataset. This specification documents both the v1 (legacy, activities-only) and v2 (activities + facts + riddles + websites + suggestions) surfaces of the canonical Drew Thoennes implementation so the API contract is preserved for self-hosting and historical reference.
  contact:
    name: Drew Thoennes
    url: https://github.com/drewthoennes/Bored-API
  license:
    name: MIT
    url: https://github.com/drewthoennes/Bored-API/blob/master/license
  x-status: deprecated-hosted-instance
  x-status-notes: The official hosted instance at https://www.boredapi.com/ is no longer reliably reachable. The reference implementation remains open source and can be self-hosted. The App Brewery community fork (https://bored-api.appbrewery.com) provides an actively maintained hosted mirror with a slightly different path scheme.
servers:
- url: https://www.boredapi.com
  description: Original hosted instance (historically; intermittent / dead as of 2024)
- url: http://localhost:8080
  description: Self-hosted local instance (npm install && npm start)
tags:
- name: Riddles
  description: Random or keyed riddles with difficulty filter (v2 only).
paths:
  /api/v2/riddles:
    get:
      tags:
      - Riddles
      summary: Get a Random Riddle
      description: Returns a single random riddle, optionally filtered by difficulty (easy, normal, hard).
      operationId: getRandomRiddle
      parameters:
      - name: difficulty
        in: query
        description: Filter riddles by difficulty.
        required: false
        schema:
          type: string
          enum:
          - easy
          - normal
          - hard
      responses:
        '200':
          description: A random riddle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiddleEnvelope'
        '400':
          $ref: '#/components/responses/Error'
  /api/v2/riddles/{key}:
    get:
      tags:
      - Riddles
      summary: Get a Riddle by Key
      description: Returns the riddle matching the supplied key.
      operationId: getRiddleByKey
      parameters:
      - $ref: '#/components/parameters/KeyPathParam'
      - name: difficulty
        in: query
        required: false
        schema:
          type: string
          enum:
          - easy
          - normal
          - hard
      responses:
        '200':
          description: The riddle matching the supplied key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiddleEnvelope'
        '400':
          $ref: '#/components/responses/Error'
components:
  schemas:
    Riddle:
      type: object
      properties:
        question:
          type: string
          example: What has keys but can't open locks?
        answer:
          type: string
          example: A piano.
        difficulty:
          type: string
          enum:
          - easy
          - normal
          - hard
          default: normal
          example: easy
        source:
          type: string
          format: uri
          description: Optional URL backing the riddle.
          example: ''
        key:
          type: string
          example: '7654321'
      required:
      - question
      - answer
      - difficulty
      - key
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Failed to query due to error in arguments
      required:
      - error
    RiddleEnvelope:
      type: object
      properties:
        riddle:
          $ref: '#/components/schemas/Riddle'
      required:
      - riddle
  responses:
    Error:
      description: Bad request or query argument error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    KeyPathParam:
      name: key
      in: path
      required: true
      description: Unique key identifying the resource.
      schema:
        type: string