openapi: 3.0.0
info:
  title: Reddit Post API
  description: |
    The Reddit Post API returns one Reddit post by its ID or link: its title, text, author, subreddit, score, comment count and media, who removed it if it was removed, and its first top-level comments in the order Reddit shows them. Share links from the Reddit app work too. NSFW posts are returned only when `safe` is `off`.

    **Cross-linking**: the `id` of a post returned by the Reddit Search API can be passed as `post_id`.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Reddit Post
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["reddit_post"]
            default: "reddit_post"
        - name: post_id
          in: query
          required: false
          description: ID of the post, such as `t3_1pf7vqp` from Reddit Search results or `1pf7vqp` from a post link. Required if url is not provided, and cannot be combined with it.
          schema:
            type: string
            pattern: '^(?:t3_)?[0-9a-z]{1,13}$'
        - name: url
          in: query
          required: false
          description: Link to the post on reddit.com, old.reddit.com or redd.it, or a share link from the Reddit app. Required if post_id is not provided, and cannot be combined with it.
          schema:
            type: string
            maxLength: 2048
        - name: safe
          in: query
          required: false
          description: Set to `off` to return an NSFW post.
          schema:
            type: string
            enum: ["active", "off"]
            default: "active"
      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 post was returned.
        post:
          $ref: '#/components/schemas/PostResult'
        comments:
          type: array
          description: First top-level comments on the post, up to 10, in the order Reddit shows them.
          items:
            $ref: '#/components/schemas/Comment'
    SearchMetadata:
      type: object
      required: [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 post
        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
        post_id:
          type: string
          description: ID of the post requested
        url:
          type: string
          description: Link to the post requested
        safe:
          type: string
          description: NSFW filter setting
    PostResult:
      type: object
      required: [id, link, subreddit, iso_date]
      properties:
        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.
        type:
          type: string
          description: Kind of content the post holds, such as `text`, `image`, `video`, `gallery`, `link`, `poll` or `crosspost`.
        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.
        text:
          type: string
          description: Text of the post, with paragraphs separated by blank lines.
        text_links:
          type: array
          description: Links to pages outside Reddit found in the text of the post.
          items:
            type: string
        text_images:
          type: array
          description: Images placed in the text of the post, in the order they appear.
          items:
            type: string
        text_videos:
          type: array
          description: Links to the HLS playlists of videos placed in the text of the post, in the order they appear.
          items:
            type: string
        external_link:
          type: string
          description: Link to the page the post shares.
        domain:
          type: string
          description: Domain of the page the post shares.
        image:
          type: string
          description: Image or GIF file uploaded with the post.
        thumbnail:
          type: string
          description: Preview image Reddit shows for the post.
        images:
          type: array
          description: Gallery images of the post in display order.
          items:
            $ref: '#/components/schemas/PostImage'
        video:
          $ref: '#/components/schemas/PostVideo'
        removed_by:
          type: string
          description: Who removed the post, `author`, `moderator` or `reddit`.
        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.
        is_archived:
          type: boolean
          description: Whether the post is archived.
    PostAuthor:
      type: object
      required: [username, 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, 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 or profile.
    PostCrosspostParent:
      type: object
      required: [id, link]
      properties:
        id:
          type: string
          description: Reddit fullname of the original post, prefixed with `t3_`.
        link:
          type: string
          description: Link to the original post on Reddit.
    PostImage:
      type: object
      required: [link]
      properties:
        link:
          type: string
          description: Link to the largest version of the image Reddit shows.
        caption:
          type: string
          description: Caption the author gave the image.
    PostVideo:
      type: object
      required: [hls_link]
      properties:
        link:
          type: string
          description: Link to the video as an MP4 file in its largest size.
        hls_link:
          type: string
          description: Link to the HLS playlist of the video.
        duration:
          type: integer
          description: Length of the video in seconds.
        width:
          type: integer
          description: Width of the MP4 file in pixels.
        height:
          type: integer
          description: Height of the MP4 file in pixels.
    Comment:
      type: object
      required: [position, id, iso_date]
      properties:
        position:
          type: integer
          description: Position of the comment among the top-level comments.
        id:
          type: string
          description: Reddit fullname of the comment, prefixed with `t1_`.
        author:
          $ref: '#/components/schemas/CommentAuthor'
        text:
          type: string
          description: Text of the comment, with paragraphs separated by blank lines.
        text_links:
          type: array
          description: Links to pages outside Reddit found in the comment.
          items:
            type: string
        image:
          type: string
          description: Image or GIF posted in the comment.
        link:
          type: string
          description: Link to the comment on Reddit.
        score:
          type: integer
          description: Net vote score of the comment.
        awards_count:
          type: integer
          description: Number of awards the comment has received.
        iso_date:
          type: string
          format: date-time
          description: Date the comment was posted, in ISO 8601.
        edited_iso_date:
          type: string
          format: date-time
          description: Date the comment was last edited, in ISO 8601.
        distinguished:
          type: string
          description: Role the author commented with, such as `moderator` or `admin`.
        is_submitter:
          type: boolean
          description: Whether the author of the comment also wrote the post.
        is_pinned:
          type: boolean
          description: Whether the comment is pinned to the top of the comments.
        is_locked:
          type: boolean
          description: Whether the comment is locked for replies.
        is_score_hidden:
          type: boolean
          description: Whether Reddit still hides the score of the comment.
        is_removed:
          type: boolean
          description: Whether the comment was removed or deleted.
    CommentAuthor:
      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.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
