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": "", "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.