{
  "openapi": "3.1.0",
  "info": {
    "title": "FetchLayer Reddit API — Search",
    "version": "1.0.0",
    "description": "Find content, communities, and users across Reddit."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/reddit"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error, on every route. Branch on code and retryable rather than on the text; on a 5xx the text is generic. MCP tool errors carry the same fields in structuredContent, and as a JSON text block.",
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in words. For a 400, what to change."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status, repeated in the body."
          },
          "code": {
            "type": "string",
            "description": "The kind of error, stable: invalid_input, unauthorized, insufficient_credits, forbidden, not_found, expired, quota_exceeded, cancelled, time_limit, temporarily_unavailable, posts_unavailable, store_unreachable, upstream_error, internal_error, tool_error. A platform may add its own; more may be added. Treat a code you do not recognise by its retryable flag."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether asking again can succeed."
          },
          "requestId": {
            "type": "string",
            "description": "This request’s id, also sent as the X-Request-Id header. Quote it when reporting a problem."
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "With invalid_input when the request's parameters are refused before the request runs: the parameters that were missing. Always present on those errors, empty when nothing was missing."
          }
        },
        "required": [
          "error",
          "code",
          "retryable",
          "requestId"
        ]
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key. No Reddit OAuth credentials are required."
      }
    }
  },
  "paths": {
    "/search": {
      "post": {
        "operationId": "search",
        "tags": [
          "Search"
        ],
        "summary": "Posts matching a keyword — globally or within a subreddit",
        "description": "Search Reddit posts by keyword. Optionally narrow to a specific subreddit. Results include title, score, comment count, author, and permalink.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search keyword or phrase."
                  },
                  "subreddit": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Limit search to a specific subreddit."
                  },
                  "sort": {
                    "type": "string",
                    "description": "Sort order: relevance, new, comments, top or hot.",
                    "example": "relevance"
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Maximum number of results to return. With the default `pages: 1`, a request returns at most one page of results, which can be fewer than `limit`.",
                    "example": "25"
                  },
                  "time": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Time filter: hour, day, week, month, year, or all."
                  },
                  "pages": {
                    "type": "integer",
                    "description": "How many pages of results to return, at most. A page holds as many results as Reddit shows on it (often 7 to 25), so a larger `limit` needs `pages` above 1 to be filled. When the pages run out before `limit` and more results remain, `notes` says so and `nextCursor` continues. Each page is billed as one, so the credits a request costs equal the pages it actually returns (see `pagesScraped` in the response).",
                    "example": "1"
                  },
                  "after": {
                    "type": "string",
                    "description": "Continue where a previous response stopped: pass its nextCursor. Use the same query, subreddit, sort and time."
                  },
                  "include": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Extra fields per post: [\"body\"] adds the full body of each text post as bodyText, bodyHtml and bodyMarkdown. Off by default: it adds about 1–2 seconds when a few results are text posts, and up to about 20 when all of them are. [\"media\"] adds media[] to each post, in display order: images, gallery slides with captions, videos with a still (poster), link preview images, with sizes, plus blurredUrl for NSFW or spoiler media. Same price as without it."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "developer tools",
                    "subreddit": "webdev",
                    "sort": "top",
                    "time": "week",
                    "limit": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestedUrl": {
                      "type": "string",
                      "description": "The Reddit URL the request was for."
                    },
                    "finalUrl": {
                      "type": "string",
                      "description": "Final URL after redirects."
                    },
                    "listingType": {
                      "type": "string",
                      "description": "Always search for a successful response."
                    },
                    "query": {
                      "type": "string",
                      "description": "Search query."
                    },
                    "sort": {
                      "type": "string",
                      "description": "Applied sort order."
                    },
                    "time": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Applied time filter."
                    },
                    "subredditFilter": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Applied subreddit filter."
                    },
                    "resultCountText": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Result count text displayed by Reddit."
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Reddit post ID without the t3_ prefix."
                          },
                          "fullname": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Reddit post fullname, including the t3_ prefix."
                          },
                          "subreddit": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Subreddit name without the r/ prefix."
                          },
                          "subredditPrefixed": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Subreddit name with the r/ prefix."
                          },
                          "author": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Author username."
                          },
                          "title": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Post title."
                          },
                          "permalink": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Absolute URL of the Reddit comments page."
                          },
                          "shortlink": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Short redd.it URL for the post."
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Absolute post content URL."
                          },
                          "domain": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Hostname or Reddit domain associated with the post."
                          },
                          "createdAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "ISO 8601 creation timestamp."
                          },
                          "flair": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Post flair text, or null when absent."
                          },
                          "score": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Post score."
                          },
                          "scoreText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Score text as displayed by Reddit."
                          },
                          "commentCount": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Comment count."
                          },
                          "commentCountText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Comment count text as displayed by Reddit."
                          },
                          "previewText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Text preview for self posts, or null when unavailable."
                          },
                          "thumbnailUrl": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Post thumbnail URL, or null when unavailable."
                          },
                          "nsfw": {
                            "type": "boolean",
                            "description": "Whether the post is marked NSFW."
                          },
                          "spoiler": {
                            "type": "boolean",
                            "description": "Whether the post is marked as a spoiler."
                          },
                          "locked": {
                            "type": "boolean",
                            "description": "Whether the post is locked."
                          },
                          "stickied": {
                            "type": "boolean",
                            "description": "Whether the post is stickied."
                          },
                          "removed": {
                            "type": [
                              "boolean",
                              "null"
                            ],
                            "description": "true when the post has been removed or deleted, false when it is live, null when its status could not be read for this response (notes says how many). Reddit leaves removed posts out of this listing, so a listed post is false; null appears only when its status could not be read."
                          },
                          "removedByCategory": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Almost always null: Reddit leaves removed posts out of this listing. When removed is true (rare), the same values as the post route."
                          },
                          "authorId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The author’s account id (t2_…), which stays the same if the username changes."
                          },
                          "subredditId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The subreddit’s id (t5_…)."
                          },
                          "numCrossposts": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "Exact number of crossposts; null when it could not be checked."
                          },
                          "postType": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "What kind of post it is: text, link, image, video or gallery; null when not known. Only text posts have a body."
                          },
                          "media": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "additionalProperties": true,
                              "properties": {
                                "kind": {
                                  "type": "string",
                                  "description": "image, gallery_item (one slide of a gallery, in Reddit's order), video, or link_preview (a link post's preview image)."
                                },
                                "url": {
                                  "type": "string",
                                  "description": "The real, unblurred media. Reddit-hosted video has no single MP4 with audio: url is the video's HLS streaming playlist (.m3u8, audio and video together, playable by HLS players such as ffmpeg, VLC or hls.js). Embedded videos (for example Streamable or YouTube) point to the provider's page."
                                },
                                "width": {
                                  "type": [
                                    "number",
                                    "null"
                                  ],
                                  "description": "Width in pixels; null when not known."
                                },
                                "height": {
                                  "type": [
                                    "number",
                                    "null"
                                  ],
                                  "description": "Height in pixels; null when not known."
                                },
                                "caption": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "gallery_item only: the slide's caption, null when it has none."
                                },
                                "poster": {
                                  "type": [
                                    "object",
                                    "null"
                                  ],
                                  "additionalProperties": true,
                                  "description": "video only: a still image of the video, { url, width, height }."
                                },
                                "blurredUrl": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Reddit's blurred version of an NSFW or spoiler post's media, when Reddit provides one; otherwise null. The post keeps its nsfw and spoiler flags; url is always the real media."
                                }
                              }
                            },
                            "description": "Only with include [\"media\"]. The post's media, in display order. null for a text post, a removed post, or a post whose media could not be read on that request; notes says how many. Image and gallery originals (i.redd.it) are stable addresses. Preview and poster addresses (preview.redd.it, external-preview.redd.it) can expire or change, so **download them rather than linking to them long-term.**"
                          },
                          "linkUrl": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "What a non-text post points to: the external site, the image, video or gallery, or a crosspost’s original. Null for a text post. url is unchanged."
                          },
                          "bodyText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Only with include [\"body\"]: the full body of a text post as plain text. Null when postType is not text. For a text post, null means a title-only post with no body text, or — when a note says so — a body that could not be returned this time."
                          },
                          "bodyHtml": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Only with include [\"body\"]: the same body as HTML."
                          },
                          "bodyMarkdown": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Only with include [\"body\"]: the same body as Markdown, converted from the HTML — it renders the same, but is not byte-identical to what the author typed."
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "listingTitle": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Display title of the listing, or null when unavailable."
                    },
                    "itemCount": {
                      "type": "number",
                      "description": "Number of entries returned in items."
                    },
                    "nextPageUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The next page’s address, or null at the end. On endpoints that take `after` it is an api.fetchlayer.dev address: POST it with your key to get the next page (a body is optional; fields you send override the address), or pass its `after` parameter as `after`."
                    },
                    "prevPageUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The previous page’s address (its `before` parameter is the cursor), or null."
                    },
                    "pagesRequested": {
                      "type": "number",
                      "description": "Number of pages requested."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Pages of results returned. This is what the request is billed at: 1 credit per page actually returned, never per page requested."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 time the result was produced."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The data source: always the platform id, \"reddit\"."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats about this result, for example how many posts had a removal status that could not be checked."
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as after to continue exactly where this response stopped, even partway through a page; null at the end."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "listingType": "search",
                      "query": "developer tools",
                      "sort": "top",
                      "time": "week",
                      "subredditFilter": "webdev",
                      "items": [
                        {
                          "id": "1wi3mi5",
                          "title": "Is vibe coding creating a hidden technical debt crisis?",
                          "subreddit": "webdev",
                          "author": "powleads",
                          "score": 3241,
                          "commentCount": 418,
                          "url": "https://www.reddit.com/r/webdev/comments/1wi3mi5/",
                          "createdAt": "2026-08-13T03:00:00.000Z",
                          "nsfw": false,
                          "spoiler": false,
                          "locked": false,
                          "stickied": false
                        }
                      ],
                      "itemCount": 1,
                      "pagesRequested": 1,
                      "pagesScraped": 1,
                      "transport": "reddit"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/search-comments": {
      "post": {
        "operationId": "search-comments",
        "tags": [
          "Search"
        ],
        "summary": "Comments matching a keyword — globally or within a subreddit",
        "description": "Search Reddit comments by keyword. Optionally narrow to a specific subreddit. Results include comment body, score, author, subreddit, and permalink.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search keyword or phrase."
                  },
                  "subreddit": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Limit search to a specific subreddit."
                  },
                  "sort": {
                    "type": "string",
                    "description": "Sort order: relevance, new, comments, top.",
                    "example": "relevance"
                  },
                  "time": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Time filter: hour, day, week, month, year, or all."
                  },
                  "after": {
                    "type": "string",
                    "description": "Continue where a previous response stopped: pass its nextCursor. Use the same query, subreddit, sort and time."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Maximum number of results to return.",
                    "example": "25"
                  },
                  "pages": {
                    "type": "integer",
                    "description": "How many pages of results to return, at most. Each page is billed as one, so the credits a request costs equal the pages it actually returns (see `pagesScraped` in the response).",
                    "example": "1"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "mcp",
                    "sort": "top",
                    "time": "all",
                    "limit": 25
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestedUrl": {
                      "type": "string",
                      "description": "The Reddit URL the request was for."
                    },
                    "finalUrl": {
                      "type": "string",
                      "description": "Final URL after redirects."
                    },
                    "listingType": {
                      "type": "string",
                      "description": "Always comment-search for a successful response."
                    },
                    "listingTitle": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Display title of the result listing."
                    },
                    "resultCountText": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Result count text displayed by Reddit."
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Comment ID without the t1_ prefix."
                          },
                          "fullname": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Reddit comment fullname."
                          },
                          "subreddit": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Subreddit name without the r/ prefix."
                          },
                          "subredditPrefixed": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Subreddit name with the r/ prefix."
                          },
                          "author": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Comment author."
                          },
                          "parentPostTitle": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Parent post title."
                          },
                          "parentPostAuthor": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Parent post author."
                          },
                          "parentPostUrl": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Parent post URL."
                          },
                          "permalink": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Absolute comment permalink."
                          },
                          "contextUrl": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Comment URL including Reddit context."
                          },
                          "fullCommentsUrl": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "URL of the full comments page."
                          },
                          "createdAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "ISO 8601 creation timestamp."
                          },
                          "score": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Comment score."
                          },
                          "scoreText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Score text as displayed by Reddit."
                          },
                          "replyCount": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Reply count when available."
                          },
                          "replyCountText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Reply count text as displayed by Reddit."
                          },
                          "bodyText": {
                            "type": "string",
                            "description": "Plain-text comment body."
                          },
                          "bodyHtml": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "HTML comment body when available."
                          },
                          "authorFlair": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The commenter’s flair in that community, as text (emoji as :code:). null means the commenter wears no flair; it means unknown only when the lookup failed, and notes then says so."
                          },
                          "authorFlairRichtext": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "description": "The same flair as parts: text parts ({ type, text }) and emoji parts ({ type, code, imageUrl }). null when authorFlair is null."
                          },
                          "distinguished": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Moderator/admin distinction, or null."
                          },
                          "stickied": {
                            "type": "boolean",
                            "description": "Whether the comment is stickied."
                          },
                          "removed": {
                            "type": [
                              "boolean",
                              "null"
                            ],
                            "description": "Always null here: comment history and search results do not show whether a comment was removed. Use the post or comment permalink endpoint for removal status."
                          },
                          "removedBy": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null here, for the same reason as removed."
                          },
                          "authorId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The author’s account id (t2_…)."
                          },
                          "subredditId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The subreddit’s id (t5_…)."
                          },
                          "postFullname": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The fullname of the post the comment is on (t3_…)."
                          },
                          "parentFullname": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "What the comment replies to: another comment (t1_…), or the post itself (t3_…) for a top-level comment."
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "itemCount": {
                      "type": "number",
                      "description": "Number of comments returned in items."
                    },
                    "nextCursorUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The next page as an api.fetchlayer.dev address, or null at the end. POST it with your key to get the next page (a body is optional; fields you send override the address). Its `after` parameter is nextCursor."
                    },
                    "prevCursorUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Previous page address, or null."
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as after, with the same query, subreddit, sort and time, to get the next page; null at the end."
                    },
                    "pagesRequested": {
                      "type": "number",
                      "description": "Number of pages requested."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Pages of results returned. This is what the request is billed at: 1 credit per page actually returned, never per page requested."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 time the result was produced."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The data source: always the platform id, \"reddit\"."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "listingType": "comment-search",
                      "items": [
                        {
                          "id": "xyz123",
                          "bodyText": "MCP has been a game changer for my workflow.",
                          "subreddit": "programming",
                          "author": "devuser",
                          "score": 342,
                          "permalink": "https://www.reddit.com/r/programming/comments/.../comment/...",
                          "createdAt": "2026-08-13T03:00:00.000Z",
                          "stickied": false
                        }
                      ],
                      "itemCount": 1,
                      "pagesRequested": 1,
                      "pagesScraped": 1,
                      "transport": "reddit"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/search-communities": {
      "post": {
        "operationId": "search-communities",
        "tags": [
          "Search"
        ],
        "summary": "Find subreddits by keyword",
        "description": "Search for subreddits matching a keyword. Returns community names, descriptions, URLs, metadata text, and NSFW status.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search keyword."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Max results.",
                    "example": "25"
                  },
                  "pages": {
                    "type": "integer",
                    "description": "How many pages of results to return, at most. Each page holds 10 results. If omitted, results continue until `limit` is reached (or the 45s time budget ends, returning partial results with `incompleteReason: \"scrape_timeout\"`), billed as `ceil(items returned / 10)`. If passed, results are capped at that many pages and billed per page actually returned (see `pagesScraped` in the response)."
                  },
                  "after": {
                    "type": "string",
                    "description": "Continue where a previous response stopped: pass its nextCursor. Use the same query."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "programming",
                    "limit": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestedUrl": {
                      "type": "string",
                      "description": "The Reddit URL the request was for."
                    },
                    "finalUrl": {
                      "type": "string",
                      "description": "Final URL after redirects."
                    },
                    "listingType": {
                      "type": "string",
                      "description": "Always search-communities for a successful response."
                    },
                    "query": {
                      "type": "string",
                      "description": "Community search query."
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "subreddit": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Subreddit name without the r/ prefix."
                          },
                          "subredditPrefixed": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Subreddit name with the r/ prefix."
                          },
                          "title": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Community display title."
                          },
                          "descriptionText": {
                            "type": "string",
                            "description": "Plain-text community description."
                          },
                          "descriptionHtml": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "HTML community description when available."
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Absolute subreddit URL."
                          },
                          "metaText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Metadata text displayed by Reddit."
                          },
                          "nsfw": {
                            "type": "boolean",
                            "description": "Whether the community marks itself as 18+ (NSFW)."
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as after, with the same query, to continue exactly where this response stopped; null at the end."
                    },
                    "listingTitle": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Display title of the listing, or null when unavailable."
                    },
                    "itemCount": {
                      "type": "number",
                      "description": "Number of entries returned in items."
                    },
                    "nextPageUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The next page’s address, or null at the end. On endpoints that take `after` it is an api.fetchlayer.dev address: POST it with your key to get the next page (a body is optional; fields you send override the address), or pass its `after` parameter as `after`."
                    },
                    "prevPageUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The previous page’s address (its `before` parameter is the cursor), or null."
                    },
                    "pagesRequested": {
                      "type": "number",
                      "description": "Number of pages requested."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Pages of results returned. This is what the request is billed at: 1 credit per page actually returned, never per page requested."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 time the result was produced."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The data source: always the platform id, \"reddit\"."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "listingType": "search-communities",
                      "query": "programming",
                      "items": [
                        {
                          "subreddit": "programming",
                          "subredditPrefixed": "r/programming",
                          "title": "Programming",
                          "descriptionText": "Computer Programming",
                          "url": "https://www.reddit.com/r/programming/",
                          "metaText": "Programming community",
                          "nsfw": false
                        }
                      ],
                      "itemCount": 1,
                      "pagesRequested": 1,
                      "pagesScraped": 1,
                      "transport": "reddit"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/search-users": {
      "post": {
        "operationId": "search-users",
        "tags": [
          "Search"
        ],
        "summary": "Find Reddit users by name",
        "description": "Search for Reddit users by username. Returns matching profile names, descriptions, metadata, and URLs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Username to search for."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Max results.",
                    "example": "10"
                  },
                  "pages": {
                    "type": "integer",
                    "description": "How many pages of results to return, at most. Each page holds 10 results. If omitted, results continue until `limit` is reached (or the 45s time budget ends, returning partial results with `incompleteReason: \"scrape_timeout\"`), billed as `ceil(items returned / 10)`. If passed, results are capped at that many pages and billed per page actually returned (see `pagesScraped` in the response)."
                  },
                  "after": {
                    "type": "string",
                    "description": "Continue where a previous response stopped: pass its nextCursor. Use the same query."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "spez",
                    "limit": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestedUrl": {
                      "type": "string",
                      "description": "The Reddit URL the request was for."
                    },
                    "finalUrl": {
                      "type": "string",
                      "description": "Final URL after redirects."
                    },
                    "listingType": {
                      "type": "string",
                      "description": "Always search-users for a successful response."
                    },
                    "query": {
                      "type": "string",
                      "description": "User search query."
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "username": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Reddit username."
                          },
                          "displayName": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Profile display name."
                          },
                          "descriptionText": {
                            "type": "string",
                            "description": "Plain-text profile description."
                          },
                          "descriptionHtml": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "HTML profile description when available."
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Absolute Reddit profile URL."
                          },
                          "metaText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Metadata text displayed by Reddit."
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as after, with the same query, to continue exactly where this response stopped; null at the end."
                    },
                    "listingTitle": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Display title of the listing, or null when unavailable."
                    },
                    "itemCount": {
                      "type": "number",
                      "description": "Number of entries returned in items."
                    },
                    "nextPageUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The next page’s address, or null at the end. On endpoints that take `after` it is an api.fetchlayer.dev address: POST it with your key to get the next page (a body is optional; fields you send override the address), or pass its `after` parameter as `after`."
                    },
                    "prevPageUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The previous page’s address (its `before` parameter is the cursor), or null."
                    },
                    "pagesRequested": {
                      "type": "number",
                      "description": "Number of pages requested."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Pages of results returned. This is what the request is billed at: 1 credit per page actually returned, never per page requested."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 time the result was produced."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The data source: always the platform id, \"reddit\"."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "listingType": "search-users",
                      "query": "spez",
                      "items": [
                        {
                          "username": "spez",
                          "displayName": "spez",
                          "descriptionText": "Reddit profile description.",
                          "url": "https://www.reddit.com/user/spez/",
                          "metaText": "Reddit user"
                        }
                      ],
                      "itemCount": 1,
                      "pagesRequested": 1,
                      "pagesScraped": 1,
                      "transport": "reddit"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}