openapi: 3.0.3
info:
  title: Hacker News API
  description: >-
    The official Hacker News API provides read-only access to items
    (stories, comments, jobs, Ask HNs, polls), users, and live data
    via Firebase. No authentication is required.
  version: v0
  contact:
    name: Hacker News
    url: https://github.com/HackerNews/API
  license:
    name: MIT
    url: https://github.com/HackerNews/API/blob/master/LICENSE
servers:
  - url: https://hacker-news.firebaseio.com/v0
    description: Production Firebase endpoint
tags:
  - name: Items
    description: Stories, comments, jobs, Ask HNs, polls, and pollopts.
  - name: Users
    description: User profiles.
  - name: Lists
    description: Top, new, best, ask, show, and job story lists.
  - name: Live
    description: Max item ID and recent updates.
paths:
  /item/{id}.json:
    get:
      summary: Get item by ID
      description: Returns a story, comment, job, Ask HN, poll, or pollopt by its ID.
      operationId: getItem
      tags:
        - Items
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric item ID.
          schema:
            type: integer
      responses:
        '200':
          description: Item object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
  /user/{username}.json:
    get:
      summary: Get user profile
      description: Returns a Hacker News user profile by case-sensitive username.
      operationId: getUser
      tags:
        - Users
      parameters:
        - name: username
          in: path
          required: true
          description: Case-sensitive HN username.
          schema:
            type: string
      responses:
        '200':
          description: User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /maxitem.json:
    get:
      summary: Get max item ID
      description: Returns the current largest item ID.
      operationId: getMaxItem
      tags:
        - Live
      responses:
        '200':
          description: Latest item ID
          content:
            application/json:
              schema:
                type: integer
  /topstories.json:
    get:
      summary: Get top stories
      description: Up to 500 top story IDs.
      operationId: getTopStories
      tags:
        - Lists
      responses:
        '200':
          description: Array of story IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /newstories.json:
    get:
      summary: Get new stories
      description: Up to 500 newest story IDs.
      operationId: getNewStories
      tags:
        - Lists
      responses:
        '200':
          description: Array of story IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /beststories.json:
    get:
      summary: Get best stories
      description: Up to 500 best story IDs.
      operationId: getBestStories
      tags:
        - Lists
      responses:
        '200':
          description: Array of story IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /askstories.json:
    get:
      summary: Get latest Ask HN stories
      description: Up to 200 latest Ask HN story IDs.
      operationId: getAskStories
      tags:
        - Lists
      responses:
        '200':
          description: Array of story IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /showstories.json:
    get:
      summary: Get latest Show HN stories
      description: Up to 200 latest Show HN story IDs.
      operationId: getShowStories
      tags:
        - Lists
      responses:
        '200':
          description: Array of story IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /jobstories.json:
    get:
      summary: Get latest job stories
      description: Up to 200 latest job story IDs.
      operationId: getJobStories
      tags:
        - Lists
      responses:
        '200':
          description: Array of story IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /updates.json:
    get:
      summary: Get changed items and profiles
      description: Returns items and user profiles that have recently changed.
      operationId: getUpdates
      tags:
        - Live
      responses:
        '200':
          description: Updates payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: integer
                  profiles:
                    type: array
                    items:
                      type: string
components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
          description: The unique item id.
        deleted:
          type: boolean
        type:
          type: string
          enum:
            - job
            - story
            - comment
            - poll
            - pollopt
        by:
          type: string
          description: The username of the item author.
        time:
          type: integer
          description: Unix timestamp of creation.
        text:
          type: string
        dead:
          type: boolean
        parent:
          type: integer
        poll:
          type: integer
        kids:
          type: array
          items:
            type: integer
        url:
          type: string
        score:
          type: integer
        title:
          type: string
        parts:
          type: array
          items:
            type: integer
        descendants:
          type: integer
    User:
      type: object
      properties:
        id:
          type: string
          description: Case-sensitive user id.
        delay:
          type: integer
        created:
          type: integer
          description: Unix timestamp of account creation.
        karma:
          type: integer
        about:
          type: string
        submitted:
          type: array
          items:
            type: integer