openapi: 3.0.0
info:
  title: Reddit Search API
  description: |
    The Reddit Search API returns the Reddit posts that match a query, as Reddit's search shows them, up to 7 posts per page. Searches can be restricted to one subreddit, sorted, limited to a time range and filtered for NSFW content. The first page of a search across all of Reddit also returns the `related_communities` and `related_searches` Reddit shows.

    Pages are cursor-based: pass `pagination.next_page_token` from one response as `next_page_token` to get the next page.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Reddit Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["reddit_search"]
            default: "reddit_search"
        - name: q
          in: query
          required: true
          description: Search query. Accepts Reddit search operators such as `site:` and `author:`.
          schema:
            type: string
            maxLength: 512
        - name: subreddit
          in: query
          required: false
          description: Name of the subreddit to search in.
          schema:
            type: string
            pattern: '^[A-Za-z0-9][A-Za-z0-9_]{1,20}$'
        - name: sort_by
          in: query
          required: false
          description: Sort order of the results.
          schema:
            type: string
            enum: ["relevance", "hot", "top", "new", "comment_count"]
            default: "relevance"
        - name: time_period
          in: query
          required: false
          description: Time range the posts were created in.
          schema:
            type: string
            enum: ["last_hour", "last_day", "last_week", "last_month", "last_year", "any_time"]
            default: "any_time"
        - name: safe
          in: query
          required: false
          description: Set to `off` to include NSFW results.
          schema:
            type: string
            enum: ["active", "off"]
            default: "active"
        - name: next_page_token
          in: query
          required: false
          description: Token for the next page of results, from `pagination.next_page_token` of the previous response.
          schema:
            type: string
            pattern: '^[A-Za-z0-9+/=_-]{1,4096}$'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        error:
          type: string
          description: Error message explaining why no results were returned.
        organic_results:
          type: array
          description: Posts that match the query.
          items:
            $ref: '#/components/schemas/PostResult'
        related_communities:
          type: array
          description: Communities Reddit shows next to the posts that match the query.
          items:
            $ref: '#/components/schemas/RelatedCommunity'
        related_searches:
          type: array
          description: Searches Reddit suggests for the query.
          items:
            $ref: '#/components/schemas/RelatedSearch'
        pagination:
          $ref: '#/components/schemas/Pagination'
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Reddit URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        q:
          type: string
          description: Search query
        subreddit:
          type: string
          description: Subreddit the search was restricted to
        sort_by:
          type: string
          description: Sort order of the results
        time_period:
          type: string
          description: Time range the posts were created in
        safe:
          type: string
          description: NSFW filter setting
        next_page_token:
          type: string
          description: Token of the page requested
    Pagination:
      type: object
      properties:
        next_page_token:
          type: string
          description: Token to pass as `next_page_token` to get the next page of results.
    PostResult:
      type: object
      required: [position, id, title, link, subreddit, score, comments, iso_date]
      properties:
        position:
          type: integer
          description: Position of the post in the results.
        id:
          type: string
          description: Reddit fullname of the post, prefixed with `t3_`.
        title:
          type: string
          description: Title of the post.
        link:
          type: string
          description: Link to the post on Reddit.
        author:
          $ref: '#/components/schemas/PostAuthor'
        subreddit:
          $ref: '#/components/schemas/PostSubreddit'
        crosspost_parent:
          $ref: '#/components/schemas/PostCrosspostParent'
        score:
          type: integer
          description: Net vote score of the post.
        comments:
          type: integer
          description: Number of comments on the post.
        snippet:
          type: string
          description: Excerpt of the post's text that Reddit shows under the title.
        matching_comment:
          $ref: '#/components/schemas/PostMatchingComment'
        thumbnail:
          type: string
          description: Thumbnail image of the post.
        images:
          type: array
          description: Gallery images of the post in display order.
          items:
            $ref: '#/components/schemas/PostImage'
        iso_date:
          type: string
          format: date-time
          description: Date the post was created, in ISO 8601.
        is_nsfw:
          type: boolean
          description: Whether the post is marked NSFW.
        is_spoiler:
          type: boolean
          description: Whether the post is marked as a spoiler.
    PostAuthor:
      type: object
      required: [username, id, link]
      properties:
        username:
          type: string
          description: Username of the author.
        id:
          type: string
          description: Reddit fullname of the author, prefixed with `t2_`.
        link:
          type: string
          description: Link to the author's profile.
    PostSubreddit:
      type: object
      required: [name, id, link]
      properties:
        name:
          type: string
          description: Name of the subreddit the post was made in, or `u_` followed by the username for a post on a user's profile.
        id:
          type: string
          description: Reddit fullname of the subreddit, prefixed with `t5_`.
        link:
          type: string
          description: Link to the subreddit or profile.
        icon:
          type: string
          description: Icon image of the subreddit.
        is_nsfw:
          type: boolean
          description: Whether the subreddit is marked NSFW.
    PostCrosspostParent:
      type: object
      required: [id, link]
      properties:
        id:
          type: string
          description: Reddit fullname of the original post, prefixed with `t3_`.
        title:
          type: string
          description: Title of the original post.
        link:
          type: string
          description: Link to the original post on Reddit.
    PostMatchingComment:
      type: object
      required: [id, snippet]
      properties:
        id:
          type: string
          description: Reddit fullname of the comment, prefixed with `t1_`.
        snippet:
          type: string
          description: Excerpt of the comment that Reddit shows under the post.
    PostImage:
      type: object
      required: [image]
      properties:
        image:
          type: string
          description: Link to the largest version of the image Reddit shows.
        width:
          type: integer
          description: Width of the original image in pixels.
        height:
          type: integer
          description: Height of the original image in pixels.
    RelatedCommunity:
      type: object
      required: [position, id, name, link]
      properties:
        position:
          type: integer
          description: Position of the community in the related communities.
        id:
          type: string
          description: Reddit fullname of the community, prefixed with `t5_`.
        name:
          type: string
          description: Name of the community.
        link:
          type: string
          description: Link to the community on Reddit.
        description:
          type: string
          description: Public description of the community.
        icon:
          type: string
          description: Icon image of the community.
        weekly_visitors:
          type: integer
          description: Number of people who visited the community in the past week.
        weekly_contributions:
          type: integer
          description: Number of posts and comments made in the community in the past week.
        is_nsfw:
          type: boolean
          description: Whether the community is marked NSFW.
    RelatedSearch:
      type: object
      required: [query, link]
      properties:
        query:
          type: string
          description: Search query text.
        link:
          type: string
          description: Link to the Reddit search for the query.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong