openapi: 3.1.0
info:
  version: 1.0.0
  title: Hacker News API
  license:
    name: MIT
    url: https://github.com/HackerNews/API/blob/master/LICENSE
security: []
servers:
  - url: https://hacker-news.firebaseio.com/v0
components:
  schemas: {}
  parameters: {}
paths:
  /item/{id}.json:
    get:
      operationId: getItem
      summary: Retrieve an item from the API.
      parameters:
        - schema:
            type: string
          required: true
          name: id
          in: path
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The item's unique id.
                  deleted:
                    type: boolean
                    description: "`true` if the item is deleted."
                  type:
                    type: string
                    enum:
                      - job
                      - story
                      - comment
                      - poll
                      - pollopt
                    description: The type of the item.
                  by:
                    type: string
                    description: The username of the item's author.
                  time:
                    type: integer
                    description: Creation date of the item, in Unix Time.
                  text:
                    type: string
                    description: The comment, story or poll text. HTML.
                  dead:
                    type: boolean
                    description: "`true` if the item is dead."
                  parent:
                    type: integer
                    description: "The comment's parent: either another comment or the relevant
                      story."
                  poll:
                    description: The pollopt's associated poll.
                  kids:
                    type: array
                    items:
                      type: integer
                    description: The ids of the item's comments, in ranked display order.
                  url:
                    type: string
                    description: The URL of the story.
                  score:
                    type: integer
                    description: The story's score, or the votes for a pollopt.
                  title:
                    type: string
                    description: The title of the story, poll or job. HTML.
                  parts:
                    type: array
                    items:
                      type: integer
                      description: A list of related pollopts, in display order.
                  descendants:
                    type: number
                    description: In the case of stories or polls, the total comment count.
                required:
                  - id
  /user/{id}.json:
    get:
      operationId: getUser
      summary: Retrieve a user from the API.
      parameters:
        - schema:
            type: string
          required: true
          name: id
          in: path
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The user's unique username. Case-sensitive. Required.
                  created:
                    type: integer
                    description: Creation date of the user, in [Unix
                      Time](http://en.wikipedia.org/wiki/Unix_time).
                  karma:
                    type: integer
                    description: The user's karma.
                  about:
                    type: string
                    description: The user's optional self-description. HTML.
                  submitted:
                    type: array
                    items:
                      type: integer
                    description: List of the user's stories, polls and comments.
                required:
                  - id
                  - created
                  - karma
  /maxitem.json:
    get:
      operationId: getMaxItem
      summary: Retrieve the current largest item id.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: integer
  /topstories.json:
    get:
      operationId: topstories.json
      summary: Retrieve top 500 entries of story type topstories
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /newstories.json:
    get:
      operationId: newstories.json
      summary: Retrieve top 500 entries of story type newstories
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /beststories.json:
    get:
      operationId: beststories.json
      summary: Retrieve top 500 entries of story type beststories
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /askstories.json:
    get:
      operationId: askstories.json
      summary: Retrieve top 500 entries of story type askstories
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /showstories.json:
    get:
      operationId: showstories.json
      summary: Retrieve top 500 entries of story type showstories
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /jobstories.json:
    get:
      operationId: jobstories.json
      summary: Retrieve top 500 entries of story type jobstories
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
  /updates.json:
    get:
      operationId: updates
      summary: Get a list of updates to items and profiles.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: integer
                  profiles:
                    type: array
                    items:
                      type: string
                required:
                  - items
                  - profiles
webhooks: {}