upriver-ai Products API

openapi: 3.2.0
info:
  title: Upriver Products API
  description: A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads.
  version: 1.0.0
servers:
- url: https://api.upriver.ai
  description: Production API server
tags:
- name: Products
paths:
  /v1/brand/products:
    post:
      tags:
      - Products
      summary: Products List
      description: 'Returns a list of products associated with a brand. Requires **brand_url** on every request, including pagination requests that send **cursor**. When **cursor** is provided, **brand_url** must match the brand encoded in that cursor.


        Response format:

        - **json**: Returns structured data with product list (default)

        - **text**: Returns natural language report


        Returns verified products and services; pricing plans, features, gift cards, documentation and signup actions are excluded. Use limit=1–20 and optionally filter by tier: primary or secondary. Products are discovered in bounded batches, with primary offerings preferred within each batch; this is not a global ranking or an exhaustive catalog. Continue with next_cursor and the same tier filter. A page may be empty while has_more is true.'
      operationId: brand_product
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandProductInput'
            examples:
              all:
                summary: All products
                description: Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Change brand_url to the brand you want to research.
                value:
                  brand_url: https://glossier.com
                  limit: 5
                  include:
                  - description
                  - image_url
              all_next_page:
                summary: All products — next page
                description: Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Replace cursor with next_cursor from the preceding response for this same brand and tier filter. Continue while has_more is true, even if products is empty.
                value:
                  brand_url: https://glossier.com
                  limit: 5
                  include:
                  - description
                  - image_url
                  cursor: REPLACE_WITH_NEXT_CURSOR
              primary:
                summary: Primary products
                description: Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Change brand_url to the brand you want to research.
                value:
                  brand_url: https://glossier.com
                  limit: 5
                  include:
                  - description
                  - image_url
                  tier: primary
              primary_next_page:
                summary: Primary products — next page
                description: Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Replace cursor with next_cursor from the preceding response for this same brand and tier filter. Continue while has_more is true, even if products is empty.
                value:
                  brand_url: https://glossier.com
                  limit: 5
                  include:
                  - description
                  - image_url
                  tier: primary
                  cursor: REPLACE_WITH_NEXT_CURSOR
              secondary:
                summary: Secondary products
                description: Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Change brand_url to the brand you want to research.
                value:
                  brand_url: https://glossier.com
                  limit: 5
                  include:
                  - description
                  - image_url
                  tier: secondary
              secondary_next_page:
                summary: Secondary products — next page
                description: Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Replace cursor with next_cursor from the preceding response for this same brand and tier filter. Continue while has_more is true, even if products is empty.
                value:
                  brand_url: https://glossier.com
                  limit: 5
                  include:
                  - description
                  - image_url
                  tier: secondary
                  cursor: REPLACE_WITH_NEXT_CURSOR
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandProductResponse'
        '404':
          description: No results found for the given brand or product.
          content:
            application/json:
              example:
                detail: No products found on https://example.com
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-agent-description: Get a paginated list of products for a brand. Provide brand_url on every request, including when paging. Accepts limit=1–20 and an optional tier filter (primary, secondary). Non-products are excluded. Repeat the same tier filter with next_cursor. Ordering is local to discovery batches, not a global ranking; empty pages can still have a continuation.
      x-agent-params:
      - brand_url
      - limit
      - cursor
      - tier
  /v1/brand/product:
    post:
      tags:
      - Products
      summary: Product Details
      description: 'Provides details for a specific product including description, features, and pricing. Provide as much information as you have — more context improves accuracy.


        **Input:**

        - **product_name**: Required.

        - **product_url**, **brand_url**, **brand_name**: Optional. At least one required to identify the brand.


        **Effort Levels:**

        - **low**: fast extraction from the product page.

        - **high**: includes competitive research (alternatives).'
      operationId: brand_product_detail
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandProductDetailInput'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandProductDetailResponse'
        '404':
          description: No results found for the given brand or product.
          content:
            application/json:
              example:
                detail: No products found on https://example.com
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-agent-description: Get details for a specific product. Requires product_name and at least one of product_url, brand_url, or brand_name. Provide as much as you have — more context improves results. Use values from the /v1/brand/products response when chaining.
      x-agent-params:
      - product_name
      - product_url
      - brand_url
      - brand_name
components:
  schemas:
    BrandProductInput:
      properties:
        brand_url:
          type: string
          title: Brand Url
          description: Required. Brand website URL to research for products. HTTP URLs are upgraded to HTTPS. Provide this on every request, including pagination requests that also send a `cursor`.
          example: https://glossier.com
        brand_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Name
          description: Deprecated — brand name is now resolved automatically from the URL. This field is accepted but ignored.
          deprecated: true
        response_format:
          $ref: '#/components/schemas/ResponseFormat'
          description: 'Format for the response: ''json'' for structured data, ''text'' for natural language'
          default: json
          example: json
        cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
          description: 'Use this to paginate through results, providing the `next_cursor` returned from a previous request. When set, `brand_url` is still required and must match the brand encoded in the cursor. If omitted, the first page of results is returned. '
        tier:
          anyOf:
          - type: string
            enum:
            - primary
            - secondary
          - type: 'null'
          title: Tier
          description: 'Optional product relationship filter: primary is what the business mainly sells or provides; secondary covers complementary or incidental offerings outside its main business. Omit to include all verified products, including those whose relationship cannot be established. Use the same filter on every pagination request.'
        limit:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Limit
          description: Maximum products to return, from 1 to 20. Fewer may be returned when the website supports fewer offerings.
          default: 10
        include:
          anyOf:
          - items:
              type: string
              enum:
              - description
              - image_url
            type: array
          - type: 'null'
          title: Include
          description: 'Which per-product fields to return. Allowed values: ''description'', ''image_url''. Omit the field to get ''description'' only (the default). Add ''image_url'' to also get product images. An explicit empty list returns name, url, and tier when known. Unrequested fields are omitted. Example: ["description", "image_url"]'
      type: object
      required:
      - brand_url
      title: BrandProductInput
      description: Input model for brand product research endpoint.
    BrandProductDetailResponse:
      properties:
        name:
          type: string
          title: Name
          description: Official product name
          example: Boy Brow
        description:
          type: string
          title: Description
          description: Detailed product description
          example: A brushable, buildable brow gel that thickens and shapes brows. Available in 5 shades, Boy Brow uses a short bristle brush to deposit a flexible, buildable hold formula.
        features:
          items:
            type: string
          type: array
          title: Features
          description: Key features
          example:
          - Flexible, buildable hold
          - Short bristle brush for precise application
          - Available in 5 shades
          - Conditioning formula with cellulose and oleic acid
        specifications:
          additionalProperties:
            type: string
          type: object
          title: Specifications
          description: Technical specifications
          example:
            shades: Blond, Brown, Black, Auburn, Clear
            size: 3.12 g / 0.11 oz
            type: Brow gel
        price:
          anyOf:
          - type: string
          - type: 'null'
          title: Price
          description: Price information
          example: $18.00
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
          description: Currency code
          example: USD
        reviews_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Reviews Summary
          description: Summary of reviews
          example: 4.5 stars from 3,200+ reviews. Customers love the natural look and easy application.
        alternatives:
          items:
            type: string
          type: array
          title: Alternatives
          description: Alternative products (high effort only)
          example:
          - Benefit Gimme Brow+
          - NYX Thick It Stick It Brow Gel
        images:
          items:
            type: string
          type: array
          title: Images
          description: Product images
          example:
          - https://www.glossier.com/cdn/images/boy-brow-brown.jpg
      type: object
      required:
      - name
      - description
      title: BrandProductDetailResponse
      description: Response model for detailed product research.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BrandProductDetailInput:
      properties:
        brand_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Url
          description: The brand's website URL.
          example: https://glossier.com
        brand_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Name
          description: Deprecated — brand name is now resolved automatically from the URL. This field is accepted but ignored.
          deprecated: true
        product_name:
          type: string
          title: Product Name
          description: The name of the product to research.
          example: Boy Brow
        product_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Url
          description: The product page URL.
          example: https://www.glossier.com/products/boy-brow
        effort:
          $ref: '#/components/schemas/EffortLevel'
          description: 'Effort level: ''low'' (basic details), ''high'' (includes competitive info)'
          default: low
          example: low
      type: object
      required:
      - product_name
      title: BrandProductDetailInput
      description: Input model for detailed product research endpoint.
      example:
        product_name: Boy Brow
        product_url: https://www.glossier.com/products/boy-brow
    ProductInfo:
      properties:
        name:
          type: string
          title: Name
          description: The name of the product
          examples:
          - Boy Brow
        tier:
          anyOf:
          - type: string
            enum:
            - primary
            - secondary
          - type: 'null'
          title: Tier
          description: 'Relationship to the business: primary is its main goods or services; secondary is complementary or incidental offerings outside its main business. Omitted when website evidence is insufficient. Several or all products can be primary; this is not a popularity ranking.'
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
          description: The category or type of the product
          examples:
          - Brows
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the product
          examples:
          - A brushable, buildable brow gel that shapes and fills brows.
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: URL to the product page
          examples:
          - https://www.glossier.com/products/boy-brow
        image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Image Url
          description: URL of the product's primary image, if available.
          examples:
          - https://www.glossier.com/cdn/images/boy-brow.jpg
      type: object
      required:
      - name
      title: ProductInfo
      description: Product information from brand website.
    BrandProductResponse:
      properties:
        brand_url:
          type: string
          title: Brand Url
          description: The brand's primary website URL
          example: https://www.glossier.com
        brand_name:
          type: string
          title: Brand Name
          description: The resolved brand name
          example: Glossier
        products:
          items:
            $ref: '#/components/schemas/ProductInfo'
          type: array
          title: Products
          description: List of products found on the brand's website
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Pagination cursor for the next page of results (if available).
        has_more:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Has More
          description: Whether more pages of results are available.
          example: true
        effort:
          $ref: '#/components/schemas/EffortLevel'
          description: Depth actually traveled to produce this page (resolved; never 'auto'). 'low' = served from the catalog/listing with no per-product detail lookups; 'mid'/'high' = a growing share of results needed a detail lookup.
          default: low
          example: low
      type: object
      required:
      - brand_url
      - brand_name
      - products
      title: BrandProductResponse
      description: Response model for brand product research results.
    ResponseFormat:
      type: string
      enum:
      - json
      - text
      title: ResponseFormat
      description: Response format options for brand product research.
    EffortLevel:
      type: string
      enum:
      - auto
      - low
      - mid
      - high
      title: EffortLevel
      description: Effort level for product research.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key