openapi: 3.1.0
info:
  title: Lobsters Comments Stories API
  description: The Lobsters public API provides read access to stories, comments, tags, and user profiles from the technology-focused link aggregation community. Endpoints return JSON and are available without authentication for public data. Stories can be retrieved by hottest or newest ranking, filtered by tag, and paginated by page number.
  version: 1.0.0
  contact:
    url: https://lobste.rs/about
  license:
    name: BSD 3-Clause
    url: https://github.com/lobsters/lobsters/blob/main/LICENSE
servers:
- url: https://lobste.rs
  description: Lobsters production server
tags:
- name: Stories
  description: Technology link aggregation stories submitted by the community
paths:
  /hottest.json:
    get:
      operationId: getHottestStories
      summary: Get hottest stories
      description: Returns a paginated list of stories sorted by the hotness algorithm, combining score, age, and community activity. This is the default front page ranking.
      tags:
      - Stories
      parameters:
      - name: page
        in: query
        description: Page number for pagination (1-indexed)
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      responses:
        '200':
          description: List of hottest stories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Story'
  /newest.json:
    get:
      operationId: getNewestStories
      summary: Get newest stories
      description: Returns a paginated list of stories sorted by submission time, newest first.
      tags:
      - Stories
      parameters:
      - name: page
        in: query
        description: Page number for pagination (1-indexed)
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      responses:
        '200':
          description: List of newest stories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Story'
  /active.json:
    get:
      operationId: getActiveStories
      summary: Get active discussion stories
      description: Returns stories with recent comment activity, sorted by latest discussion time.
      tags:
      - Stories
      parameters:
      - name: page
        in: query
        description: Page number for pagination (1-indexed)
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      responses:
        '200':
          description: List of stories with active discussions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Story'
  /t/{tag}.json:
    get:
      operationId: getStoriesByTag
      summary: Get stories by tag
      description: Returns a paginated list of hottest stories filtered to a specific tag.
      tags:
      - Stories
      parameters:
      - name: tag
        in: path
        description: Tag identifier (e.g. "programming", "security")
        required: true
        schema:
          type: string
          pattern: ^[^,./]+$
      - name: page
        in: query
        description: Page number for pagination (1-indexed)
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      responses:
        '200':
          description: List of stories with the specified tag
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Story'
        '404':
          description: Tag not found
  /s/{short_id}.json:
    get:
      operationId: getStory
      summary: Get a story by short ID
      description: Returns a single story and its nested comment thread by the story's short identifier.
      tags:
      - Stories
      parameters:
      - name: short_id
        in: path
        description: Short alphanumeric identifier for the story (e.g. "abcdef")
        required: true
        schema:
          type: string
          maxLength: 6
      responses:
        '200':
          description: Story with nested comments
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Story'
                - type: object
                  properties:
                    comments:
                      type: array
                      description: Nested comment thread for the story
                      items:
                        $ref: '#/components/schemas/Comment'
        '404':
          description: Story not found
components:
  schemas:
    Story:
      type: object
      description: A community-submitted technology link or text post
      properties:
        short_id:
          type: string
          description: Short alphanumeric identifier for the story
          example: abcdef
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the story was submitted
        title:
          type: string
          description: Title of the story
          example: Interesting technology article
        url:
          type: string
          format: uri
          nullable: true
          description: URL of the linked resource; null for text-only posts
        score:
          type: integer
          description: Net vote score (upvotes minus downvotes)
        flags:
          type: integer
          description: Number of flags the story has received
        comment_count:
          type: integer
          description: Total number of comments on the story
        description:
          type: string
          description: HTML-rendered description or body text for text posts
          nullable: true
        description_plain:
          type: string
          description: Plain text description or body text for text posts
          nullable: true
        submitter_user:
          type: string
          description: Username of the user who submitted the story
          example: alice
        user_is_author:
          type: boolean
          description: Whether the submitter is the author of the linked content
        tags:
          type: array
          description: List of tag names applied to the story, sorted alphabetically
          items:
            type: string
          example:
          - programming
          - security
      required:
      - short_id
      - created_at
      - title
      - score
      - flags
      - comment_count
      - submitter_user
      - user_is_author
      - tags
    Comment:
      type: object
      description: A community discussion comment on a story
      properties:
        short_id:
          type: string
          description: Short alphanumeric identifier for the comment
        short_id_url:
          type: string
          format: uri
          description: Full URL to the comment's short-id redirect
        url:
          type: string
          format: uri
          description: Full URL to the comment in context of its story
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the comment was posted
        last_edited_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last edit
        is_deleted:
          type: boolean
          description: Whether the comment has been deleted by the author
        is_moderated:
          type: boolean
          description: Whether the comment has been removed by a moderator
        score:
          type: integer
          description: Net vote score for the comment
        flags:
          type: integer
          description: Number of flags the comment has received
        parent_comment:
          type: string
          nullable: true
          description: Short ID of the parent comment; null for top-level comments
        comment:
          type: string
          description: HTML-rendered comment text
        comment_plain:
          type: string
          description: Plain text comment body
        depth:
          type: integer
          description: Nesting depth in the comment thread (0 = top level)
        commenting_user:
          type: string
          description: Username of the comment author
      required:
      - short_id
      - short_id_url
      - url
      - created_at
      - last_edited_at
      - is_deleted
      - is_moderated
      - score
      - flags
      - comment
      - comment_plain
      - depth
      - commenting_user