openapi: 3.0.0
info:
  title: Reddit Ad Library API
  description: |
    Search for ads on Reddit's Ad Library to gain insights into advertising campaigns, creative content, and targeting strategies.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Reddit Ad Library Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to `reddit_ad_library` for Reddit Ad Library search
          schema:
            type: string
            default: "reddit_ad_library"
            enum: ["reddit_ad_library"]
        - name: q
          in: query
          required: false
          description: Search query to filter ads
          schema:
            type: string
        - name: industry
          in: query
          required: false
          description: Filter by industry. Multiple values can be comma-separated.
          schema:
            type: string
            enum: ["EDUCATION", "TECH_B2C", "TECH_B2B", "RETAIL_AND_ECOMMERCE", "ENTERTAINMENT", "GAMING", "FINANCIAL_SERVICES", "HEALTH_AND_BEAUTY", "CONSUMER_PACKAGED_GOODS", "EMPLOYMENT", "AUTO", "TRAVEL", "REAL_ESTATE", "GAMBLING_AND_FANTASY_SPORTS", "POLITICS_AND_GOVERNMENT", "OTHER"]
        - name: budget_category
          in: query
          required: false
          description: Filter by budget category. Multiple values can be comma-separated.
          schema:
            type: string
            enum: ["LOW", "MEDIUM", "HIGH"]
        - name: post_type
          in: query
          required: false
          description: Filter by post type. Multiple values can be comma-separated.
          schema:
            type: string
            enum: ["VIDEO", "IMAGE", "CAROUSEL", "FREE_FORM"]
        - name: placements
          in: query
          required: false
          description: Filter by ad placements. Multiple values can be comma-separated.
          schema:
            type: string
            enum: ["COMMENTS_PAGE", "FEED"]
        - name: objective_type
          in: query
          required: false
          description: Filter by campaign objective. Multiple values can be comma-separated.
          schema:
            type: string
            enum: ["CLICKS", "IMPRESSIONS", "CONVERSIONS", "VIDEO_VIEWABLE_IMPRESSIONS", "APP_INSTALLS"]
      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'
        ads:
          type: array
          description: Array of Reddit ads matching the search criteria
          items:
            $ref: '#/components/schemas/Ad'
        error:
          type: string
          description: Error message when no results are found
    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 Ad Library 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:
        q:
          type: string
          description: Search query used
        industry:
          type: string
          description: Industry filter applied
        budget_category:
          type: string
          description: Budget category filter applied
        post_type:
          type: string
          description: Post type filter applied
        placements:
          type: string
          description: Placements filter applied
        objective_type:
          type: string
          description: Objective type filter applied
    Ad:
      type: object
      properties:
        engine:
          type: string
          description: "Search engine used"
        id:
          type: string
          description: Unique identifier for the ad
        budget_category:
          type: string
          description: Budget category of the ad
        industry:
          type: string
          description: Industry category of the ad
        placements:
          type: array
          description: Placement locations for the ad
          items:
            type: string
        objective:
          type: string
          description: Campaign objective of the ad
        creative:
          $ref: '#/components/schemas/Creative'
        profile_info:
          $ref: '#/components/schemas/ProfileInfo'
    Creative:
      type: object
      properties:
        id:
          type: string
          description: Reddit post ID of the creative
        type:
          type: string
          description: Type of creative content
        content:
          type: array
          description: Array of content items in the creative
          items:
            $ref: '#/components/schemas/CreativeContent'
        headline:
          type: string
          description: Headline text of the ad
        body:
          type: string
          description: Body text of the ad
        thumbnail_url:
          type: string
          description: URL of the thumbnail image
        allow_comments:
          type: boolean
          description: Whether comments are allowed on the ad
        created_at:
          type: string
          description: Timestamp when the creative was created
        profile_id:
          type: string
          description: Reddit profile ID of the advertiser
        post_url:
          type: string
          description: URL to the Reddit post
    CreativeContent:
      type: object
      properties:
        destination_url:
          type: string
          description: Landing page URL when the ad is clicked
        display_url:
          type: string
          description: Display URL shown on the ad
        call_to_action:
          type: string
          description: Call to action text on the button
        media_url:
          type: string
          description: URL of the media content (image or video)
    ProfileInfo:
      type: object
      properties:
        name:
          type: string
          description: Reddit username of the advertiser
        snoovatar_icon_url:
          type: string
          description: URL of the advertiser's profile avatar
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong