> ## Documentation Index > Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt > Use this file to discover all available pages before exploring further. # Products List > 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 The service prioritizes prominent and popular products from the brand's website. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/brand/products openapi: 3.1.0 info: title: Upriver 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 security: [] tags: - name: Brands - name: Products - name: Creators - name: Audience - name: Sponsorships - name: Trends - name: Breakout Topics - name: Taxonomy 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 The service prioritizes prominent and popular products from the brand's website. operationId: brand_product requestBody: content: application/json: schema: $ref: '#/components/schemas/BrandProductInput' 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: [] components: schemas: BrandProductInput: properties: brand_url: type: string title: Brand Url description: >- Required. Brand website URL to research for products. 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/apis__models__brand_product__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. limit: type: integer maximum: 20 minimum: 5 title: Limit description: Maximum number of products to return per page. 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 and url only. Unrequested fields are omitted from each result. Example: ["description", "image_url"] type: object required: - brand_url title: BrandProductInput description: Input model for brand product research endpoint. 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. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError apis__models__brand_product__ResponseFormat: type: string enum: - json - text title: ResponseFormat description: Response format options for brand product research. ProductInfo: properties: name: type: string title: Name description: The name of the product examples: - Boy Brow 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. EffortLevel: type: string enum: - auto - low - mid - high title: EffortLevel description: Effort level for 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 securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````