openapi: 3.0.3
info:
  title: jService Trivia Categories API
  description: 'jService is an open source Ruby on Rails API that serves Jeopardy! questions

    (called "clues"), answers, and categories sourced from the J! Archive fan site.


    The schema in this document is reconstructed from the upstream source repository

    (`sottenad/jService`, MIT licensed). The historical public deployment at

    https://jservice.io is offline as of 2025 (parked / for-sale holding page); the

    project remains self-hostable against PostgreSQL.


    All endpoints return JSON. None require authentication; no rate limits are

    documented in the source.

    '
  version: 1.0.0
  contact:
    name: Steve Ottenad
    url: https://github.com/sottenad/jService
  license:
    name: MIT
    url: https://github.com/sottenad/jService/blob/master/LICENSE.txt
  x-status: deprecated
  x-status-reason: Original hosted endpoint at jservice.io is offline; spec preserved from source.
  x-data-source: https://j-archive.com
servers:
- url: http://jservice.io
  description: Original hosted endpoint (historical, currently offline)
- url: http://localhost:3000
  description: Default local Rails development server
tags:
- name: Categories
  description: Category collections of clues.
paths:
  /api/categories:
    get:
      tags:
      - Categories
      summary: List Categories
      description: List categories with offset/count pagination. Default count 1, maximum 100.
      operationId: listCategories
      parameters:
      - name: count
        in: query
        description: Number of categories to return (max 100).
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 1
      - name: offset
        in: query
        description: Pagination offset.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: Array of categories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
  /api/category:
    get:
      tags:
      - Categories
      summary: Get Single Category
      description: Get one category by ID, including all of its clues.
      operationId: getCategory
      parameters:
      - name: id
        in: query
        description: Category ID.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: A category with embedded clues.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryWithClues'
        '404':
          description: Category not found.
components:
  schemas:
    Clue:
      type: object
      properties:
        id:
          type: integer
        answer:
          type: string
          description: The Jeopardy "answer" (read by the host).
        question:
          type: string
          description: The Jeopardy "question" (the contestant's response).
        value:
          type: integer
          nullable: true
          description: Dollar value of the clue. Null for Final Jeopardy clues.
        airdate:
          type: string
          format: date-time
        category_id:
          type: integer
        game_id:
          type: integer
          nullable: true
        invalid_count:
          type: integer
          nullable: true
          description: Number of times users have flagged this clue as invalid.
      required:
      - id
      - answer
      - question
      - category_id
    Category:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        clues_count:
          type: integer
          default: 0
      required:
      - id
      - title
    CategoryWithClues:
      allOf:
      - $ref: '#/components/schemas/Category'
      - type: object
        properties:
          clues:
            type: array
            items:
              $ref: '#/components/schemas/Clue'