openapi: 3.0.0
info:
  title: Pinterest Search API
  description: |
    The Pinterest Search API returns the pins Pinterest shows for a query to a signed-out visitor: images with their sizes, title, description, outbound link, date, reactions, board and pinner, the stream of video pins, and the price, discount and brand of product pins. Results can be limited to video pins or product pins, can leave out AI-generated pins, and follow the country of the viewer. The first page also returns the related searches and refinement groups Pinterest suggests and, on some queries, a row of products.

    Pages are cursor-based: pass `pagination.next_page_token` from one response as `next_page_token` to get the next page. Pinterest's feeds have no last page, and later pages can repeat pins from earlier ones, so de-duplicate on `id`.

    Pin `id` values are the ids Pinterest gives signed-out visitors. A pin's own page on Pinterest asks for a login, so no pin link is returned; the pinner and board links open without one.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Pinterest Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["pinterest_search"]
            default: "pinterest_search"
        - name: q
          in: query
          required: true
          description: >-
            Search query, up to 600 characters. Non-Latin text and emoji have lower limits: Japanese text
            allows about 198 characters on the first page or 145 with next_page_token.
            The exact limit depends on the characters and token.
            Over-limit requests are rejected before a search or charge.
          schema:
            type: string
            maxLength: 600
        - name: filter_by
          in: query
          required: false
          description: Kind of pins to return. `all` returns every pin, `videos` returns video pins and `products` returns product pins.
          schema:
            type: string
            enum: ["all", "videos", "products"]
            default: "all"
        - name: less_ai
          in: query
          required: false
          description: Set to `true` to show fewer AI-generated pins, as Pinterest's Less AI filter does.
          schema:
            type: boolean
            default: false
        - name: country
          in: query
          required: false
          description: Two-letter country code of the viewer. Pinterest picks the pins for the viewer's country and prices products in its currency. `filter_by=products` is available in `at`, `au`, `br`, `ca`, `ch`, `de`, `es`, `fr`, `gb`, `it`, `mx`, `nl` and `us`.
          schema:
            type: string
            enum: ["ar", "at", "au", "br", "ca", "ch", "cl", "co", "cz", "de", "dk", "es", "fi", "fr", "gb", "gr", "hu", "id", "ie", "in", "it", "jp", "kr", "mx", "nl", "no", "nz", "ph", "pl", "pt", "ro", "ru", "se", "sk", "tr", "us", "za"]
            default: "us"
        - 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.
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        related_searches:
          type: array
          description: Refinements Pinterest suggests for the query.
          items:
            $ref: '#/components/schemas/RelatedSearch'
        filters:
          type: array
          description: Groups of refinements Pinterest shows under a label, such as a diet or a season.
          items:
            $ref: '#/components/schemas/Filter'
        shopping_results:
          type: array
          description: Product pins Pinterest shows in a row between the pins.
          items:
            $ref: '#/components/schemas/Pin'
        pins:
          type: array
          description: Pins that match the query, in Pinterest's order.
          items:
            $ref: '#/components/schemas/Pin'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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: Pinterest 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
        filter_by:
          type: string
          description: Kind of pins requested
        less_ai:
          type: boolean
          description: Whether fewer AI-generated pins were requested
        country:
          type: string
          description: Country of the viewer
        next_page_token:
          type: string
          description: Token of the page requested
    SearchInformation:
      type: object
      required: [query_displayed]
      properties:
        query_displayed:
          type: string
          description: Query Pinterest searched for.
        showing_results_for:
          type: string
          description: Corrected spelling of the query that Pinterest shows results for.
    RelatedSearch:
      type: object
      required: [query, title]
      properties:
        query:
          type: string
          description: Full query of the refinement, to pass as `q`.
        title:
          type: string
          description: Short label Pinterest shows for the refinement.
        thumbnail:
          type: string
          description: Image Pinterest shows next to the refinement.
    Filter:
      type: object
      required: [title, options]
      properties:
        title:
          type: string
          description: Label of the group.
        options:
          type: array
          description: Refinements in the group.
          items:
            $ref: '#/components/schemas/FilterOption'
    FilterOption:
      type: object
      required: [title, query]
      properties:
        title:
          type: string
          description: Short label Pinterest shows for the refinement.
        query:
          type: string
          description: Full query of the refinement, to pass as `q`.
    Pin:
      type: object
      required: [position, id, thumbnail, original, iso_date, pinner, board]
      properties:
        position:
          type: integer
          description: Position of the pin in its list.
        id:
          type: string
          description: Pinterest's id of the pin.
        title:
          type: string
          description: Title of the pin.
        description:
          type: string
          description: Description the pinner wrote for the pin.
        alt_text:
          type: string
          description: Alternative text of the pin's image.
        link:
          type: string
          description: Website link the pin points to.
        source:
          $ref: '#/components/schemas/PinSource'
        thumbnail:
          type: string
          description: Thumbnail of the pin's image, 236 pixels wide.
        original:
          $ref: '#/components/schemas/PinImage'
        dominant_color:
          type: string
          description: Dominant color of the image as a hex code.
        reactions:
          type: integer
          description: Number of reactions to the pin.
        saves:
          type: integer
          description: Number of times the pin was saved.
        iso_date:
          type: string
          format: date-time
          description: Date the pin was created, in ISO 8601.
        is_video:
          type: boolean
          description: Whether the pin is a video.
        video:
          $ref: '#/components/schemas/PinVideo'
        price:
          type: string
          description: Price of the product as Pinterest shows it.
        extracted_price:
          type: number
          description: Price of the product as a number.
        original_price:
          type: string
          description: Price of the product before the discount.
        extracted_original_price:
          type: number
          description: Price of the product before the discount, as a number.
        discount:
          type: string
          description: Discount on the product as Pinterest shows it.
        currency:
          type: string
          description: ISO 4217 code of the price's currency.
        is_in_stock:
          type: boolean
          description: Whether the product is in stock.
        is_out_of_stock:
          type: boolean
          description: Whether the product is out of stock.
        brand:
          type: string
          description: Brand of the product.
        rating:
          type: number
          description: Average rating of the product.
        reviews:
          type: integer
          description: Number of reviews of the product.
        pinner:
          $ref: '#/components/schemas/Pinner'
        board:
          $ref: '#/components/schemas/Board'
    PinSource:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Domain of the website the pin links to.
        title:
          type: string
          description: Title of the linked page.
        site_name:
          type: string
          description: Name of the linked website.
        type:
          type: string
          description: Kind of the linked page, such as `article`, `recipe` or `product`.
    PinImage:
      type: object
      required: [link, width, height]
      properties:
        link:
          type: string
          description: Link to the image at its original size.
        width:
          type: integer
          description: Width of the original image in pixels.
        height:
          type: integer
          description: Height of the original image in pixels.
    PinVideo:
      type: object
      required: [link, duration, thumbnail]
      properties:
        link:
          type: string
          description: Link to the video's HLS stream.
        mp4_link:
          type: string
          description: Link to an MP4 file of the video.
        duration:
          type: number
          description: Length of the video in seconds.
        thumbnail:
          type: string
          description: First frame of the video.
    Pinner:
      type: object
      required: [id, username, name, link]
      properties:
        id:
          type: string
          description: Pinterest's id of the user who saved the pin.
        username:
          type: string
          description: Username of the pinner.
        name:
          type: string
          description: Display name of the pinner.
        link:
          type: string
          description: Link to the pinner's Pinterest profile.
        avatar:
          type: string
          description: Profile picture of the pinner.
        followers:
          type: integer
          description: Number of followers of the pinner.
        is_verified:
          type: boolean
          description: Whether Pinterest verified the pinner's identity.
        is_verified_merchant:
          type: boolean
          description: Whether the pinner is a verified merchant.
    Board:
      type: object
      required: [id, name, link, pins]
      properties:
        id:
          type: string
          description: Pinterest's id of the board the pin is saved to.
        name:
          type: string
          description: Name of the board.
        link:
          type: string
          description: Link to the board on Pinterest.
        pins:
          type: integer
          description: Number of pins on the board.
    Pagination:
      type: object
      required: [next_page_token]
      properties:
        next_page_token:
          type: string
          description: Token to pass as `next_page_token` to get the next page of results.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
