openapi: 3.0.3
info:
  title: Reddit JSON Listing API
  description: |-
    JSON api listing for Subreddits and Users.

    Request must have `User-Agent` header set to custom values and not empty.
  version: v1
servers:
  - url: https://reddit.com
    description: Reddit
tags:
  - name: Listing
    description: API listing
paths:
  /{type}/{name}.json:
    get:
      tags:
        - Listing
      summary: Get Subreddit Listings
      description: |-
        Fetches subreddit listing.

        If the subreddit name does not exist (case insensitive),
        this endpoint will redirect to `/subreddits/search.json?q={name}`
        with this kind of response body:

        ```json
        {
            "kind": "Listing",
            "data": {
                "after": null,
                "dist": 0,
                "modhash": "<hash>",
                "geo_filter": "",
                "children": [],
                "before": null
            }
        }
        ```

        Currently, Best way to check wether the subreddit exists or not
        is the `data.after` and `data.before` is null, and `data.children` array is empty.

        To get the proper casing of Subreddit name, take the
        first element in `data.children` and takes it subreddit name.

        So target this: `data.children[0].data.subreddit` to get proper
        subreddit name.

        To get the proper casing of a user name, target `data.children[0].data.author`.

        In the `data.children[].data` there are two possible `kind` values:
          - `t1`
          - `t3`

        `t1` represents data is a comment data, while `t3` is a Link (Post) data.

        What we want the most is `t3` type of data. So `t1` type of data should
        be skipped.
      parameters:
        - in: path
          name: type
          schema:
            type: string
            enum:
              - r
              - user
          required: true
          description: |-
            The type of listing to fetch.

              * `r` fetches subreddit listing.
              * `user` fetches user listing (comments and posts).
        - in: path
          name: name
          schema:
            type: string
          required: true
          description: |-
            The subreddit / username to fetch.
        - in: query
          name: after
          schema:
            type: string
          description: |-
            `after` can be filled with post `name`.

            Easiest to find this value is in the `response body` on
            `data.after`.

            `after` tells Reddit to look up posts after
            this value.

            `after` cannot be used together with `before`.
        - in: query
          name: before
          schema:
            type: string
          description: |-
            like `after` query param, but reversed direction.

            Cannot be used together with `after`.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 0
            maximum: 100
          description: |-
            The number of posts to fetch.

            If unset, defaults to `25`.

            Maximum value to fetch is `100`.
          example: 25
        - in: header
          name: User-Agent
          schema:
            type: string
            default: bluemage/v1
      operationId: getListing
      responses:
        "200":
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListingResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                type: object

components:
  schemas:
    ListingResponse:
      type: object
      required:
        - kind
        - data
      properties:
        kind:
          type: string
          enum:
            - Listing
        data:
          $ref: "#/components/schemas/ListingData"
    ListingData:
      type: object
      required:
        - after
        - dist
        - modhash
        - geo_filter
        - children
        - before
      properties:
        after:
          type: string
          nullable: true
          example: t3_1ep7k5l
          description: |-
            To get next post, use this value as `after`
            in request query.

            `null` if there's no more posts.
        dist:
          type: integer
          example: 25
          description: |-
            The number of posts fetched.
        modhash:
          type: string
          description: hash of the transaction request
          example: tcxu4bdbnvdbd6206ae0b13557bc8a626e33178f5e2de97c5e
        geo_filter:
          type: string
          nullable: true
          description: Not really known. AFAIK, Always returns null or empty string.
        children:
          type: array
          items:
            $ref: "#/components/schemas/ListingChildData"
    ListingChildData:
      oneOf:
        - $ref: "#/components/schemas/T1"
        - $ref: "#/components/schemas/T3"
    T1:
      type: object
      description: |-
        This is listed because this item type is a possibility.

        `t1` item type is unwanted for fetching image posts since
        it only contains comment data.
      properties:
        kind:
          type: string
          enum:
            - t1
    T3:
      type: object
      description: |-
        `t3` item type is a post (link) data.

        This is the item type to look for image posts.

        Not all fields are listed here, only fields that are relevant are
        listed to reduce deserializing errors.
      properties:
        kind:
          type: string
          enum:
            - t3
        data:
          $ref: "#/components/schemas/T3Data"

    T3Data:
      type: object
      required:
        - subreddit
        - title
        - name
      properties:
        subreddit:
          type: string
          example: wallpaper
        author_fullname:
          type: string
          example: t2_u9xzkv0h7
        author:
          type: string
          example: foo
        title:
          type: string
          example: Frost
        thumbnail_height:
          type: integer
          example: 140
          nullable: true
        name:
          type: string
          example: t3_1d61g18
          description: unique identifier for this post.
        thumbnail_width:
          type: integer
          example: 140
          nullable: true
        is_reddit_media_domain:
          type: boolean
        thumbnail:
          type: string
          example: https://b.thumbs.redditmedia.com/TXGRPZ_6RbcF8_TQmyvXxNjaXr5bs4NZxfFCc-betlc.jpg
        post_hint:
          type: string
          example: image
        is_self:
          description: |-
            Indicates if post is targeting to the post itself when followed.

            If looking for image posts, this should be `false`.
          type: boolean
        created:
          type: integer
          format: int64
          example: 1717289447
        domain:
          type: string
          example: i.redd.it
        url_overridden_by_dest:
          type: string
          example: https://i.redd.it/qtm2jhl1324d1.png
        over_18:
          type: boolean
        is_video:
          type: boolean
          description: |-
            Indicates if post is a video.

            If looking for image posts, this should be `false`.
        url:
          type: string
          example: https://i.redd.it/un4qe8c2jqj91.png
          description: target url of the post.