openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.trychannel3.com
    description: Production environment
paths:
  /v0/search:
    post:
      tags:
        - channel3-api
      summary: Search
      description: Search for products.
      operationId: search_v0_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegacyInternalSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/LegacyInternalProduct'
                type: array
                title: Response Search V0 Search Post
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  Could not fetch image from image_url. Please ensure the url is
                  valid and publicly accessible.
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Internal Server Error
      security:
        - APIKeyHeader: []
  /v0/health:
    get:
      tags:
        - channel3-api
      summary: Health Check
      description: >-
        Health check endpoint.


        Returns unhealthy (503) if the event loop lag exceeds 1 second,

        indicating the server is too busy to handle requests promptly.


        This endpoint also records availability metrics for status page
        integration.
      operationId: health_check_v0_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Health Check V0 Health Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Internal Server Error
  /v0/products/{product_id}:
    get:
      tags:
        - channel3-api
      summary: Product Detail
      description: Get detailed information about a specific product by its ID.
      operationId: get_product_detail_v0_products__product_id__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: product_id
          in: path
          required: true
          schema:
            type: string
            title: Product Id
        - name: redirect_mode
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/RedirectMode'
              - type: 'null'
            description: >-
              Deprecated and ignored. Each offer now contains its own merchant
              URL.
            deprecated: true
            title: Redirect Mode
          description: >-
            Deprecated and ignored. Each offer now contains its own merchant
            URL.
          deprecated: true
        - name: website_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
              - type: 'null'
            description: >-
              Optional list of website IDs to constrain the buy URL to, relevant
              if multiple merchants exist. Accepts website IDs or domains (e.g.
              "nike.com").
            title: Website Ids
          description: >-
            Optional list of website IDs to constrain the buy URL to, relevant
            if multiple merchants exist. Accepts website IDs or domains (e.g.
            "nike.com").
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyInternalProductDetail'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Product not found
          content:
            application/json:
              example:
                detail: Product not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/websites:
    get:
      tags:
        - channel3-api
      summary: Websites
      description: >-
        Resolve a website URL to its ID and best_commission_rate. Tip:
        website_ids filters accept domains directly, so this lookup is most
        useful for retrieving commission rates.
      operationId: find_website_by_url_v0_websites_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
            title: Query
        - name: country
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - US
                  - GB
                  - EU
                  - AU
                  - CA
                  - IE
                  - DE
                  - AT
                  - FR
                  - BE
                  - IT
                  - ES
                  - NL
                  - SE
                  - FI
                  - PT
                  - CZ
                  - GR
                  - RO
                type: string
              - type: 'null'
            description: >-
              ISO 3166-1 alpha-2 country code that `best_commission_rate` is
              scoped to. Defaults to 'US' when unset.
            title: Country
          description: >-
            ISO 3166-1 alpha-2 country code that `best_commission_rate` is
            scoped to. Defaults to 'US' when unset.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/Website'
                  - type: 'null'
                title: Response Find Website By Url V0 Websites Get
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Website not found
          content:
            application/json:
              example:
                detail: No website found matching 'acme'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            const website = await client.websites.retrieve({ query: 'query' });

            console.log(website.id);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            website = client.websites.retrieve(
                query="query",
            )
            print(website.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\twebsite, err := client.Websites.Get(context.TODO(), channel3go.WebsiteGetParams{\n\t\tQuery: \"query\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", website.ID)\n}\n"
        - lang: CLI
          source: |-
            channel3 websites retrieve \
              --api-key 'My API Key' \
              --query query
  /v0/brands:
    get:
      tags:
        - channel3-api
      summary: Search Brands
      description: Find a brand by name.
      operationId: find_brand_by_name_v0_brands_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
            title: Query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Brand not found
          content:
            application/json:
              example:
                detail: No brand found matching 'acme'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            const brand = await client.brands.find({ query: 'query' });

            console.log(brand.id);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            brand = client.brands.find(
                query="query",
            )
            print(brand.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrand, err := client.Brands.Find(context.TODO(), channel3go.BrandFindParams{\n\t\tQuery: \"query\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", brand.ID)\n}\n"
        - lang: CLI
          source: |-
            channel3 brands find \
              --api-key 'My API Key' \
              --query query
  /v0/brands/{brand_id}:
    get:
      tags:
        - channel3-api
      summary: Brand Detail
      description: Get detailed information about a specific brand by its ID.
      operationId: get_brand_detail_v0_brands__brand_id__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: brand_id
          in: path
          required: true
          schema:
            type: string
            title: Brand Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Brand not found
          content:
            application/json:
              example:
                detail: Brand not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/list-brands:
    get:
      tags:
        - channel3-api
      summary: List Brands
      description: |-
        Lists all brands, sorted alphabetically.
        Supports pagination with the cursor parameter.
      operationId: list_brands_v0_list_brands_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Max results (1-100)
            default: 20
            title: Limit
          description: Max results (1-100)
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Pagination cursor
            title: Cursor
          description: Pagination cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedListBrandsResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/enrich:
    post:
      tags:
        - channel3-api
      summary: Enrich Product
      description: >-
        **Deprecated** — use POST /v1/lookup instead.


        Search by product URL, get back full product information from Channel3's
        product database.


        If the product is not found in the database, the endpoint will attempt
        real-time

        retrieval from the product page. This fallback returns basic product
        information

        (price, images, title) without full enrichment.
      operationId: enrich_product_url_v0_enrich_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyInternalProductDetail'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
        '404':
          description: Product URL returned 404 or 410
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Product URL returned 404
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
        '500':
          description: >-
            Product not found and real-time retrieval failed. This is an
            unexpected error, we'll investigate it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Failed to extract price.
        '501':
          description: >-
            Product not found and real-time retrieval is not supported. We've
            been notified and will work to enable it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Domain is not enabled for real-time retrieval.
        '504':
          description: Endpoint timed out. This should be treated the same as a 500.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Endpoint request timed out
      security:
        - APIKeyHeader: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            const response = await client.enrich.enrichURL({ url: 'url' });

            console.log(response.id);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            response = client.enrich.enrich_url(
                url="url",
            )
            print(response.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Enrich.EnrichURL(context.TODO(), channel3go.EnrichEnrichURLParams{\n\t\tEnrichRequest: channel3go.EnrichRequestParam{\n\t\t\tURL: \"url\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.ID)\n}\n"
        - lang: CLI
          source: |-
            channel3 enrich enrich-url \
              --api-key 'My API Key' \
              --url url
  /v1/search:
    post:
      tags:
        - v1
      summary: Search
      description: >-
        Search for products with pagination support.


        At least one of `query`, `image_url`, `base64_image`, or `page_token`
        must be

        provided; requests with none of these will return 422.
      operationId: search_v1_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  Could not fetch image from image_url. Ensure the URL is valid,
                  publicly accessible, and points to a supported image (jpg,
                  png, webp, gif, avif, heic).
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
        '422':
          description: >-
            Validation error — e.g., the request body provides none of 'query',
            'image_url', 'base64_image', or 'page_token'.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail:
                  - type: value_error
                    loc:
                      - body
                    msg: >-
                      Value error, At least one of 'query', 'image_url',
                      'base64_image', or 'page_token' must be provided.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Internal Server Error
        '504':
          description: Timed out fetching the provided image_url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  Timed out after 5s fetching image from image_url. Ensure the
                  URL is publicly accessible and responds promptly.
      security:
        - APIKeyHeader: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            // Automatically fetches more pages as needed.
            for await (const productDetail of client.products.search()) {
              console.log(productDetail.id);
            }
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            page = client.products.search()
            page = page.products[0]
            print(page.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Products.Search(context.TODO(), channel3go.ProductSearchParams{\n\t\tSearchRequest: channel3go.SearchRequestParam{},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
        - lang: CLI
          source: |-
            channel3 products search \
              --api-key 'My API Key'
  /v1/image-search:
    post:
      tags:
        - v1
      summary: Image Search
      description: |-
        Search the catalog by image (URL or base64), with pagination support.

        Provide exactly one of ``image_url`` or ``base64_image``. For text or
        text+image search, use ``POST /v1/search``.
      operationId: image_search_v1_image_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  Could not fetch image from image_url. Ensure the URL is valid,
                  publicly accessible, and points to a supported image (jpg,
                  png, webp, gif, avif, heic).
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
        '422':
          description: Must provide exactly one of image_url or base64_image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Internal Server Error
        '504':
          description: Timed out fetching the provided image_url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  Timed out after 5s fetching image from image_url. Ensure the
                  URL is publicly accessible and responds promptly.
      security:
        - APIKeyHeader: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            // Automatically fetches more pages as needed.
            for await (const productDetail of client.products.searchByImage()) {
              console.log(productDetail.id);
            }
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            page = client.products.search_by_image()
            page = page.products[0]
            print(page.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Products.SearchByImage(context.TODO(), channel3go.ProductSearchByImageParams{\n\t\tImageSearchRequest: channel3go.ImageSearchRequestParam{},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
        - lang: CLI
          source: |-
            channel3 products search-by-image \
              --api-key 'My API Key'
  /v1/similar:
    post:
      tags:
        - v1
      summary: Similar Products
      description: |-
        Find products similar to a given product.

        Consider setting ``filters`` to narrow results to the
        same gender, brand, category, price range, etc. when you only want
        similar items within a specific slice of the catalog.
      operationId: similar_v1_similar_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimilarProductsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Product not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Internal Server Error
      security:
        - APIKeyHeader: []
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Channel3 from '@channel3/sdk';


            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });


            // Automatically fetches more pages as needed.

            for await (const productDetail of client.products.findSimilar({
            product_id: 'product_id' })) {
              console.log(productDetail.id);
            }
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            page = client.products.find_similar(
                product_id="product_id",
            )
            page = page.products[0]
            print(page.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Products.FindSimilar(context.TODO(), channel3go.ProductFindSimilarParams{\n\t\tSimilarProductsRequest: channel3go.SimilarProductsRequestParam{\n\t\t\tProductID: \"product_id\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
        - lang: CLI
          source: |-
            channel3 products find-similar \
              --api-key 'My API Key' \
              --product-id product_id
  /v1/products/{product_id}:
    get:
      tags:
        - v1
      summary: Product Detail
      description: Get detailed information about a specific product by its ID.
      operationId: get_product_detail_v1_products__product_id__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: product_id
          in: path
          required: true
          schema:
            type: string
            title: Product Id
        - name: website_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
              - type: 'null'
            description: >-
              Optional list of website IDs to constrain the buy URL to, relevant
              if multiple merchants exist. Accepts website IDs or domains (e.g.
              "nike.com").
            title: Website Ids
          description: >-
            Optional list of website IDs to constrain the buy URL to, relevant
            if multiple merchants exist. Accepts website IDs or domains (e.g.
            "nike.com").
        - name: language
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - en
                  - de
                  - fr
                  - it
                  - es
                  - nl
                  - sv
                  - fi
                  - pt
                  - cs
                  - el
                  - ro
                type: string
              - type: 'null'
            description: >-
              ISO 639-1 language code. Matches any language when unset; defaults
              to 'en' only when country and currency are also unset.
            title: Language
          description: >-
            ISO 639-1 language code. Matches any language when unset; defaults
            to 'en' only when country and currency are also unset.
        - name: country
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - US
                  - GB
                  - EU
                  - AU
                  - CA
                  - IE
                  - DE
                  - AT
                  - FR
                  - BE
                  - IT
                  - ES
                  - NL
                  - SE
                  - FI
                  - PT
                  - CZ
                  - GR
                  - RO
                type: string
              - type: 'null'
            description: >-
              ISO 3166-1 alpha-2 country code. Matches any country when unset;
              defaults to 'US' only when language and currency are also unset.
            title: Country
          description: >-
            ISO 3166-1 alpha-2 country code. Matches any country when unset;
            defaults to 'US' only when language and currency are also unset.
        - name: currency
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - USD
                  - CAD
                  - AUD
                  - GBP
                  - EUR
                  - SEK
                  - CZK
                  - RON
                type: string
              - type: 'null'
            description: >-
              ISO 4217 currency code. When unset, inferred from `country` (e.g.
              GB -> GBP); falls back to 'USD' only when all three locale fields
              are unset.
            title: Currency
          description: >-
            ISO 4217 currency code. When unset, inferred from `country` (e.g. GB
            -> GBP); falls back to 'USD' only when all three locale fields are
            unset.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Product not found
          content:
            application/json:
              example:
                detail: Product not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            const productDetail = await client.products.retrieve('product_id');

            console.log(productDetail.id);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            product_detail = client.products.retrieve(
                product_id="product_id",
            )
            print(product_detail.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tproductDetail, err := client.Products.Get(\n\t\tcontext.TODO(),\n\t\t\"product_id\",\n\t\tchannel3go.ProductGetParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", productDetail.ID)\n}\n"
        - lang: CLI
          source: |-
            channel3 products retrieve \
              --api-key 'My API Key' \
              --product-id product_id
  /v1/lookup:
    post:
      tags:
        - v1
      summary: Lookup Product
      description: >-
        Retrieve product information for any supported product URL.


        Returns the same Product model as GET /v1/products/{product_id}.

        The product_id in the response can be used with the Product Detail
        endpoint.
      operationId: lookup_product_v1_lookup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Product not found
        '422':
          description: >-
            URL is not a product page (e.g. category listing, search results,
            homepage) or is on an unsupported domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: URL is not a product page
        '500':
          description: Unable to extract product data from the given URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Product extraction failed
        '504':
          description: Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Request timed out
      security:
        - APIKeyHeader: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            const lookupResponse = await client.products.lookup({ url: 'url' });

            console.log(lookupResponse.product);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            lookup_response = client.products.lookup(
                url="url",
            )
            print(lookup_response.product)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tlookupResponse, err := client.Products.Lookup(context.TODO(), channel3go.ProductLookupParams{\n\t\tLookupRequest: channel3go.LookupRequestParam{\n\t\t\tURL: \"url\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", lookupResponse.Product)\n}\n"
        - lang: CLI
          source: |-
            channel3 products lookup \
              --api-key 'My API Key' \
              --url url
  /v1/categories/search:
    get:
      tags:
        - v1
      summary: Search Categories
      description: Search categories by free-text query.
      operationId: search_categories_public_v1_categories_search_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
            description: Free-text query (e.g. 'sofas', 'yoga mats').
            title: Query
          description: Free-text query (e.g. 'sofas', 'yoga mats').
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 20
            minimum: 1
            description: Maximum number of categories to return.
            default: 5
            title: Limit
          description: Maximum number of categories to return.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCategoriesResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Channel3 from '@channel3/sdk';


            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });


            const searchCategoriesResponse = await client.categories.search({
            query: 'x' });


            console.log(searchCategoriesResponse.categories);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            search_categories_response = client.categories.search(
                query="x",
            )
            print(search_categories_response.categories)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tsearchCategoriesResponse, err := client.Categories.Search(context.TODO(), channel3go.CategorySearchParams{\n\t\tQuery: \"x\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", searchCategoriesResponse.Categories)\n}\n"
        - lang: CLI
          source: |-
            channel3 categories search \
              --api-key 'My API Key' \
              --query x
  /v1/categories:
    get:
      tags:
        - v1
      summary: List Categories
      description: Paginated list of all categories.
      operationId: list_categories_public_v1_categories_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: roots_only
          in: query
          required: false
          schema:
            type: boolean
            description: If true, return only top-level (root) categories.
            default: false
            title: Roots Only
          description: If true, return only top-level (root) categories.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: 1-indexed page number.
            default: 1
            title: Page
          description: 1-indexed page number.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Items per page.
            default: 20
            title: Page Size
          description: Items per page.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedListCategoriesResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            // Automatically fetches more pages as needed.
            for await (const categorySummary of client.categories.list()) {
              console.log(categorySummary.has_children);
            }
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            page = client.categories.list()
            page = page.items[0]
            print(page.has_children)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Categories.List(context.TODO(), channel3go.CategoryListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
        - lang: CLI
          source: |-
            channel3 categories list \
              --api-key 'My API Key'
  /v1/categories/{slug}:
    get:
      tags:
        - v1
      summary: Category Detail
      description: Look up a category by slug.
      operationId: get_category_public_v1_categories__slug__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Category not found
          content:
            application/json:
              example:
                detail: No category found matching 'foo'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            const category = await client.categories.retrieve('slug');

            console.log(category.has_children);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            category = client.categories.retrieve(
                "slug",
            )
            print(category.has_children)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcategory, err := client.Categories.Get(context.TODO(), \"slug\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", category.HasChildren)\n}\n"
        - lang: CLI
          source: |-
            channel3 categories retrieve \
              --api-key 'My API Key' \
              --slug slug
  /v1/brands/search:
    get:
      tags:
        - v1
      summary: Search Brands
      description: Search brands by free-text query.
      operationId: search_brands_public_v1_brands_search_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
            description: Free-text query (e.g. 'Nike', 'lululemon').
            title: Query
          description: Free-text query (e.g. 'Nike', 'lululemon').
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 20
            minimum: 1
            description: Maximum number of brands to return.
            default: 5
            title: Limit
          description: Maximum number of brands to return.
        - name: country
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - US
                  - GB
                  - EU
                  - AU
                  - CA
                  - IE
                  - DE
                  - AT
                  - FR
                  - BE
                  - IT
                  - ES
                  - NL
                  - SE
                  - FI
                  - PT
                  - CZ
                  - GR
                  - RO
                type: string
              - type: 'null'
            description: >-
              ISO 3166-1 alpha-2 country code that `best_commission_rate` is
              scoped to. Defaults to 'US' when unset.
            title: Country
          description: >-
            ISO 3166-1 alpha-2 country code that `best_commission_rate` is
            scoped to. Defaults to 'US' when unset.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchBrandsResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Channel3 from '@channel3/sdk';


            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });


            const searchBrandsResponse = await client.brands.search({ query: 'x'
            });


            console.log(searchBrandsResponse.brands);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            search_brands_response = client.brands.search(
                query="x",
            )
            print(search_brands_response.brands)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tsearchBrandsResponse, err := client.Brands.Search(context.TODO(), channel3go.BrandSearchParams{\n\t\tQuery: \"x\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", searchBrandsResponse.Brands)\n}\n"
        - lang: CLI
          source: |-
            channel3 brands search \
              --api-key 'My API Key' \
              --query x
  /v1/brands:
    get:
      tags:
        - v1
      summary: List Brands
      description: Paginated list of brands, capped at the top 5,000.
      operationId: list_brands_public_v1_brands_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Max items per page (1-100).
            default: 20
            title: Limit
          description: Max items per page (1-100).
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Pagination cursor returned by a prior call. Omit for the first
              page.
            title: Cursor
          description: Pagination cursor returned by a prior call. Omit for the first page.
        - name: country
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - US
                  - GB
                  - EU
                  - AU
                  - CA
                  - IE
                  - DE
                  - AT
                  - FR
                  - BE
                  - IT
                  - ES
                  - NL
                  - SE
                  - FI
                  - PT
                  - CZ
                  - GR
                  - RO
                type: string
              - type: 'null'
            description: >-
              ISO 3166-1 alpha-2 country code that `best_commission_rate` is
              scoped to. Defaults to 'US' when unset.
            title: Country
          description: >-
            ISO 3166-1 alpha-2 country code that `best_commission_rate` is
            scoped to. Defaults to 'US' when unset.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedListBrandsResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            // Automatically fetches more pages as needed.
            for await (const brand of client.brands.list()) {
              console.log(brand.id);
            }
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            page = client.brands.list()
            page = page.items[0]
            print(page.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Brands.List(context.TODO(), channel3go.BrandListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
        - lang: CLI
          source: |-
            channel3 brands list \
              --api-key 'My API Key'
  /v1/brands/{brand_id}:
    get:
      tags:
        - v1
      summary: Brand Detail
      description: Get detailed information about a specific brand by its ID.
      operationId: get_brand_detail_public_v1_brands__brand_id__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: brand_id
          in: path
          required: true
          schema:
            type: string
            title: Brand Id
        - name: country
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - US
                  - GB
                  - EU
                  - AU
                  - CA
                  - IE
                  - DE
                  - AT
                  - FR
                  - BE
                  - IT
                  - ES
                  - NL
                  - SE
                  - FI
                  - PT
                  - CZ
                  - GR
                  - RO
                type: string
              - type: 'null'
            description: >-
              ISO 3166-1 alpha-2 country code that `best_commission_rate` is
              scoped to. Defaults to 'US' when unset.
            title: Country
          description: >-
            ISO 3166-1 alpha-2 country code that `best_commission_rate` is
            scoped to. Defaults to 'US' when unset.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Brand not found
          content:
            application/json:
              example:
                detail: Brand not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            const brand = await client.brands.retrieve('brand_id');

            console.log(brand.id);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            brand = client.brands.retrieve(
                brand_id="brand_id",
            )
            print(brand.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrand, err := client.Brands.Get(\n\t\tcontext.TODO(),\n\t\t\"brand_id\",\n\t\tchannel3go.BrandGetParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", brand.ID)\n}\n"
        - lang: CLI
          source: |-
            channel3 brands retrieve \
              --api-key 'My API Key' \
              --brand-id brand_id
  /v0/price-tracking/start:
    post:
      tags:
        - price-tracking
      summary: Start Tracking
      description: Start tracking prices for a canonical product.
      operationId: start_tracking_v0_price_tracking_start_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartTrackingRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Canonical product xyz123 not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Internal Server Error
      security:
        - APIKeyHeader: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            const subscription = await client.priceTracking.start({
              canonical_product_id: 'canonical_product_id',
            });

            console.log(subscription.canonical_product_id);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            subscription = client.price_tracking.start(
                canonical_product_id="canonical_product_id",
            )
            print(subscription.canonical_product_id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tsubscription, err := client.PriceTracking.Start(context.TODO(), channel3go.PriceTrackingStartParams{\n\t\tStartTrackingRequest: channel3go.StartTrackingRequestParam{\n\t\t\tCanonicalProductID: \"canonical_product_id\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", subscription.CanonicalProductID)\n}\n"
        - lang: CLI
          source: |-
            channel3 price-tracking start \
              --api-key 'My API Key' \
              --canonical-product-id canonical_product_id
  /v0/price-tracking/stop:
    post:
      tags:
        - price-tracking
      summary: Stop Tracking
      description: Stop tracking prices for a canonical product.
      operationId: stop_tracking_v0_price_tracking_stop_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StopTrackingRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: No active subscription for canonical product xyz123
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Internal Server Error
      security:
        - APIKeyHeader: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Channel3 from '@channel3/sdk';

            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });

            const subscription = await client.priceTracking.stop({
              canonical_product_id: 'canonical_product_id',
            });

            console.log(subscription.canonical_product_id);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            subscription = client.price_tracking.stop(
                canonical_product_id="canonical_product_id",
            )
            print(subscription.canonical_product_id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tsubscription, err := client.PriceTracking.Stop(context.TODO(), channel3go.PriceTrackingStopParams{\n\t\tStopTrackingRequest: channel3go.StopTrackingRequestParam{\n\t\t\tCanonicalProductID: \"canonical_product_id\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", subscription.CanonicalProductID)\n}\n"
        - lang: CLI
          source: |-
            channel3 price-tracking stop \
              --api-key 'My API Key' \
              --canonical-product-id canonical_product_id
  /v0/price-tracking/history/{canonical_product_id}:
    get:
      tags:
        - price-tracking
      summary: Get Price History
      description: Get price history for a canonical product.
      operationId: get_price_history_v0_price_tracking_history__canonical_product_id__get
      security:
        - APIKeyHeader: []
      parameters:
        - name: canonical_product_id
          in: path
          required: true
          schema:
            type: string
            title: Canonical Product Id
        - name: days
          in: query
          required: false
          schema:
            type: integer
            maximum: 30
            minimum: 1
            description: Number of days of history to fetch (max 30)
            default: 30
            title: Days
          description: Number of days of history to fetch (max 30)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceHistoryResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              example:
                detail: Canonical product xyz123 not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Channel3 from '@channel3/sdk';


            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });


            const priceHistory = await
            client.priceTracking.retrieveHistory('canonical_product_id');


            console.log(priceHistory.canonical_product_id);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            price_history = client.price_tracking.retrieve_history(
                canonical_product_id="canonical_product_id",
            )
            print(price_history.canonical_product_id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpriceHistory, err := client.PriceTracking.GetHistory(\n\t\tcontext.TODO(),\n\t\t\"canonical_product_id\",\n\t\tchannel3go.PriceTrackingGetHistoryParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", priceHistory.CanonicalProductID)\n}\n"
        - lang: CLI
          source: |-
            channel3 price-tracking retrieve-history \
              --api-key 'My API Key' \
              --canonical-product-id canonical_product_id
  /v0/price-tracking/subscriptions:
    get:
      tags:
        - price-tracking
      summary: List Subscriptions
      description: List your active price tracking subscriptions.
      operationId: list_subscriptions_v0_price_tracking_subscriptions_get
      security:
        - APIKeyHeader: []
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Pagination cursor
            title: Cursor
          description: Pagination cursor
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Max results (1-100)
            default: 20
            title: Limit
          description: Max results (1-100)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSubscriptionsResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@trychannel3.com.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@trychannel3.com.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              example:
                detail: >-
                  You have used all of your free credits. Add a payment method
                  to continue.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - query
                    msg: field required
                    type: value_error.missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                detail: Internal Server Error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Channel3 from '@channel3/sdk';


            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });


            // Automatically fetches more pages as needed.

            for await (const subscription of
            client.priceTracking.listSubscriptions()) {
              console.log(subscription.canonical_product_id);
            }
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            page = client.price_tracking.list_subscriptions()
            page = page.items[0]
            print(page.canonical_product_id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.PriceTracking.ListSubscriptions(context.TODO(), channel3go.PriceTrackingListSubscriptionsParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
        - lang: CLI
          source: |-
            channel3 price-tracking list-subscriptions \
              --api-key 'My API Key'
  /.well-known/ucp:
    get:
      tags:
        - ucp-well-known
      summary: Channel3 UCP catalog profile
      description: Return the catalog UCP profile.
      operationId: get_ucp_profile__well_known_ucp_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/ucp/{version}:
    get:
      tags:
        - ucp-well-known
      summary: Channel3 UCP catalog profile (versioned)
      description: Return the catalog UCP profile for a specific protocol version.
      operationId: get_ucp_profile_version__well_known_ucp__version__get
      parameters:
        - name: version
          in: path
          required: true
          schema:
            type: string
            title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ApiPhotoQuality:
      type: string
      enum:
        - professional
        - ugc
        - poor
      title: ApiPhotoQuality
      description: Photo quality classification for API responses.
    ApiProductImageType:
      type: string
      enum:
        - hero
        - lifestyle
        - on_model
        - detail
        - scale_reference
        - angle_view
        - flat_lay
        - in_use
        - packaging
        - size_chart
        - product_information
        - merchant_information
      title: ApiProductImageType
      description: Product image type classification for API responses.
    AvailabilityStatus:
      type: string
      enum:
        - InStock
        - LimitedAvailability
        - PreOrder
        - BackOrder
        - SoldOut
        - OutOfStock
        - Discontinued
        - Unknown
      title: AvailabilityStatus
    Brand:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        logo_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Logo Url
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        best_commission_rate:
          type: number
          title: Best Commission Rate
          description: >-
            The maximum commission rate for the brand in the requested country
            (default 'US'), as a percentage
          default: 0
      type: object
      required:
        - id
        - name
      title: Brand
    Category:
      properties:
        slug:
          type: string
          title: Slug
          description: URL-friendly slug (e.g. 'sofas')
        title:
          type: string
          title: Title
          description: Human-readable category title
        path:
          items:
            $ref: '#/components/schemas/CategoryRef'
          type: array
          title: Path
          description: >-
            Hierarchical path as a structured list, root first; the last entry
            is this category itself
        has_children:
          type: boolean
          title: Has Children
          description: Whether this category has subcategories
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Natural-language description of products in this category
        children:
          items:
            $ref: '#/components/schemas/CategoryRef'
          type: array
          title: Children
          description: Direct subcategories only (one level)
        attributes:
          items:
            $ref: '#/components/schemas/CategoryAttribute'
          type: array
          title: Attributes
          description: >-
            Structured attributes applicable to this category, with their
            allowed values. Usable as keys in `SearchFilters.attributes`.
      type: object
      required:
        - slug
        - title
        - has_children
      title: Category
      description: Full category representation used in detail responses.
    CategoryAttribute:
      properties:
        slug:
          type: string
          title: Slug
          description: URL-friendly identifier (e.g. 'color', 'frame-color')
        name:
          type: string
          title: Name
          description: Human-readable attribute name (e.g. 'Color')
        values:
          items:
            type: string
          type: array
          title: Values
          description: >-
            Allowed values for this attribute. May be empty when no enumerated
            value set is defined.
      type: object
      required:
        - slug
        - name
      title: CategoryAttribute
      description: A structured attribute (e.g. Color, Size) applicable to a category.
    CategoryRef:
      properties:
        slug:
          type: string
          title: Slug
          description: URL-friendly slug (e.g. 'sofas')
        title:
          type: string
          title: Title
          description: Human-readable category title
      type: object
      required:
        - slug
        - title
      title: CategoryRef
      description: Lean reference to a category, used in path and children arrays.
    CategorySummary:
      properties:
        slug:
          type: string
          title: Slug
          description: URL-friendly slug (e.g. 'sofas')
        title:
          type: string
          title: Title
          description: Human-readable category title
        path:
          items:
            $ref: '#/components/schemas/CategoryRef'
          type: array
          title: Path
          description: >-
            Hierarchical path as a structured list, root first; the last entry
            is this category itself
        has_children:
          type: boolean
          title: Has Children
          description: Whether this category has subcategories
      type: object
      required:
        - slug
        - title
        - has_children
      title: CategorySummary
      description: Lean category representation used in search hits and list rows.
    EnrichRequest:
      properties:
        url:
          type: string
          title: Url
          description: The URL of the product to enrich
      additionalProperties: false
      type: object
      required:
        - url
      title: EnrichRequest
    ErrorResponse:
      properties:
        detail:
          anyOf:
            - type: string
            - items:
                additionalProperties: true
                type: object
              type: array
          title: Detail
      type: object
      required:
        - detail
      title: ErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ImageSearchRequest:
      properties:
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
          description: Publicly accessible URL of the image to search with.
        base64_image:
          anyOf:
            - type: string
            - type: 'null'
          title: Base64 Image
          description: Base64 encoded image bytes (no data URI prefix).
        limit:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Limit
          description: Optional limit on the number of results. Default is 20, max is 30.
          default: 20
        filters:
          $ref: '#/components/schemas/SearchFilters'
          description: >-
            Optional filters. Search will only consider products that match all
            of the filters.
          default: {}
        config:
          $ref: '#/components/schemas/LocaleConfig'
          description: Optional locale configuration.
          default: {}
        page_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Token
          description: >-
            Opaque token from a previous image-search response to fetch the next
            page of results.
        segment:
          anyOf:
            - type: string
            - type: 'null'
          title: Segment
          description: >-
            Image segmentation mode. None (default) disables segmentation.
            "AUTO" segments and crops the main product automatically. A custom
            string (e.g. "shoe", "mug") segments the specified object.
      additionalProperties: false
      type: object
      title: ImageSearchRequest
      description: Image-only search request.
    LegacyInternalProduct:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        brands:
          items:
            $ref: '#/components/schemas/ProductBrand'
          type: array
          title: Brands
          description: Ordered list of brands.
        images:
          items:
            $ref: '#/components/schemas/LegacyInternalProductImage'
          type: array
          title: Images
          default: []
        categories:
          items:
            type: string
          type: array
          title: Categories
          deprecated: true
        category:
          anyOf:
            - $ref: '#/components/schemas/CategorySummary'
            - type: 'null'
          description: >-
            The single category this product belongs to, as a structured
            `CategorySummary` (slug, title, path, has_children). Replaces the
            deprecated `categories` field.
        gender:
          anyOf:
            - type: string
              enum:
                - male
                - female
                - unisex
            - type: 'null'
          title: Gender
        age:
          anyOf:
            - type: string
              enum:
                - newborn
                - infant
                - toddler
                - kids
                - adult
            - type: 'null'
          title: Age
          description: >-
            Target age group. Age-agnostic products are typically returned as
            'adult'.
        materials:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Materials
        key_features:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Key Features
        offers:
          items:
            $ref: '#/components/schemas/ProductOffer'
          type: array
          title: Offers
          description: All merchant offers for this product in the requested locale.
        variants:
          anyOf:
            - $ref: '#/components/schemas/Variants'
            - type: 'null'
          description: >-
            Variant interaction state — options, selected. Absent when the
            product has no variations.
        structured_attributes:
          additionalProperties:
            items:
              type: string
            type: array
          type: object
          title: Structured Attributes
          description: >-
            Structured attributes extracted for this product, keyed by attribute
            handle (e.g. 'color', 'material'). Values are the canonical allowed
            values for that handle.
        url:
          type: string
          title: Url
          description: Deprecated, use offers field
          deprecated: true
        brand_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand Id
          deprecated: true
        brand_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand Name
          deprecated: true
        image_urls:
          items:
            type: string
          type: array
          title: Image Urls
          description: List of image URLs (deprecated, use images field)
          default: []
          deprecated: true
        price:
          $ref: '#/components/schemas/Price'
          description: Deprecated, use offers field
          deprecated: true
        availability:
          type: string
          enum:
            - InStock
            - OutOfStock
          title: Availability
          description: Deprecated, use offers field
          deprecated: true
        score:
          type: integer
          title: Score
        image_url:
          type: string
          title: Image Url
          description: Main product image (deprecated, use images field)
          deprecated: true
        family_id_v3:
          anyOf:
            - type: string
            - type: 'null'
          title: Family Id V3
      type: object
      required:
        - id
        - title
        - url
        - price
        - availability
        - score
        - image_url
      title: LegacyInternalProduct
      description: v0 search result with score and deprecated image_url.
    LegacyInternalProductDetail:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        brands:
          items:
            $ref: '#/components/schemas/ProductBrand'
          type: array
          title: Brands
          description: Ordered list of brands.
        images:
          items:
            $ref: '#/components/schemas/LegacyInternalProductImage'
          type: array
          title: Images
          default: []
        categories:
          items:
            type: string
          type: array
          title: Categories
          deprecated: true
        category:
          anyOf:
            - $ref: '#/components/schemas/CategorySummary'
            - type: 'null'
          description: >-
            The single category this product belongs to, as a structured
            `CategorySummary` (slug, title, path, has_children). Replaces the
            deprecated `categories` field.
        gender:
          anyOf:
            - type: string
              enum:
                - male
                - female
                - unisex
            - type: 'null'
          title: Gender
        age:
          anyOf:
            - type: string
              enum:
                - newborn
                - infant
                - toddler
                - kids
                - adult
            - type: 'null'
          title: Age
          description: >-
            Target age group. Age-agnostic products are typically returned as
            'adult'.
        materials:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Materials
        key_features:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Key Features
        offers:
          items:
            $ref: '#/components/schemas/ProductOffer'
          type: array
          title: Offers
          description: All merchant offers for this product in the requested locale.
        variants:
          anyOf:
            - $ref: '#/components/schemas/Variants'
            - type: 'null'
          description: >-
            Variant interaction state — options, selected. Absent when the
            product has no variations.
        structured_attributes:
          additionalProperties:
            items:
              type: string
            type: array
          type: object
          title: Structured Attributes
          description: >-
            Structured attributes extracted for this product, keyed by attribute
            handle (e.g. 'color', 'material'). Values are the canonical allowed
            values for that handle.
        url:
          type: string
          title: Url
          description: Deprecated, use offers field
          deprecated: true
        brand_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand Id
          deprecated: true
        brand_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Brand Name
          deprecated: true
        image_urls:
          items:
            type: string
          type: array
          title: Image Urls
          description: List of image URLs (deprecated, use images field)
          default: []
          deprecated: true
        price:
          $ref: '#/components/schemas/Price'
          description: Deprecated, use offers field
          deprecated: true
        availability:
          type: string
          enum:
            - InStock
            - OutOfStock
          title: Availability
          description: Deprecated, use offers field
          deprecated: true
      type: object
      required:
        - id
        - title
        - url
        - price
        - availability
      title: LegacyInternalProductDetail
      description: v0 product detail with deprecated fields.
    LegacyInternalProductImage:
      properties:
        url:
          type: string
          title: Url
        is_main_image:
          type: boolean
          title: Is Main Image
          default: false
        is_cleaned_image:
          type: boolean
          title: Is Cleaned Image
          description: >-
            True if this URL points to a cleaned image. A cleaned image has a
            square aspect ratio and a uniform, monochromatic background. Cleaned
            images are best displayed in a product grid.
          default: false
        shot_type:
          anyOf:
            - $ref: '#/components/schemas/ApiProductImageType'
            - type: 'null'
        alt_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Alt Text
        photo_quality:
          anyOf:
            - $ref: '#/components/schemas/ApiPhotoQuality'
            - type: 'null'
          description: No longer populated for new products
          deprecated: true
      type: object
      required:
        - url
      title: LegacyInternalProductImage
      description: v0 product image with deprecated photo_quality field.
    LegacyInternalSearchConfig:
      properties:
        redirect_mode:
          anyOf:
            - $ref: '#/components/schemas/RedirectMode'
            - type: 'null'
          description: >-
            Deprecated and ignored. Each offer now contains its own merchant
            URL.
          deprecated: true
      type: object
      title: LegacyInternalSearchConfig
      description: v0 search configuration with deprecated fields.
    LegacyInternalSearchFilters:
      properties:
        brand_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Brand Ids
          description: If provided, only products from these brands will be returned
        gender:
          anyOf:
            - type: string
              enum:
                - male
                - female
            - type: 'null'
          title: Gender
        condition:
          anyOf:
            - type: string
              enum:
                - new
                - refurbished
                - used
            - type: 'null'
          title: Condition
          description: >-
            Filter by offer condition. Requires at least one offer matching the
            requested condition, locale, and any price filter. Offers without
            condition data are indexed as new.
        age:
          anyOf:
            - items:
                type: string
                enum:
                  - newborn
                  - infant
                  - toddler
                  - kids
                  - adult
              type: array
            - type: 'null'
          title: Age
          description: >-
            Filter by age group. Age-agnostic products are treated as adult
            products.
        price:
          anyOf:
            - $ref: '#/components/schemas/SearchFilterPrice'
            - type: 'null'
          description: If provided, only products within this price range will be returned
        availability:
          anyOf:
            - items:
                $ref: '#/components/schemas/AvailabilityStatus'
              type: array
            - type: 'null'
          title: Availability
          description: >-
            If provided, only products with these availability statuses will be
            returned
        sale:
          anyOf:
            - type: string
              const: on_sale
            - type: 'null'
          title: Sale
          description: >-
            If 'on_sale', only products with at least one on-sale offer (priced
            below its compare-at price) for the requested locale are returned.
            If omitted, no filter.
        website_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Website Ids
          description: >-
            If provided, only products from these websites will be returned.
            Accepts website IDs or domains (e.g. "nike.com").
        category_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Category Ids
          description: >-
            If provided, only products from these categories will be returned.
            Accepts category slugs.
        exclude_brand_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Brand Ids
          description: >-
            If provided, products from these brands will be excluded from the
            results
        exclude_website_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Website Ids
          description: >-
            If provided, products from these websites will be excluded from the
            results. Accepts website IDs or domains (e.g. "nike.com").
        exclude_category_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Category Ids
          description: >-
            If provided, products in these categories (or their descendants)
            will be excluded from the results. Accepts category slugs.
        colors:
          anyOf:
            - $ref: '#/components/schemas/SearchColorsFilter'
            - type: 'null'
          description: >-
            [Beta: filter is experimental and may be changed] If provided, find
            products containing all of these colors.
        attributes:
          anyOf:
            - additionalProperties:
                items:
                  type: string
                type: array
              type: object
            - type: 'null'
          title: Attributes
          description: >-
            If provided, only products whose extracted attributes match these
            key/value constraints will be returned. Keys are attribute handles
            (e.g. 'color', 'material') and values are lists of allowed values
            (OR within a key, AND across keys). When a category filter is also
            supplied, all keys must be valid attributes of at least one of the
            requested categories. See `Category.attributes` for the valid
            keys/values per category.
        exclude_product_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Product Ids
          description: >-
            Deprecated: this field is accepted but ignored. It has no effect on
            search results.
          deprecated: true
      additionalProperties: false
      type: object
      title: LegacyInternalSearchFilters
      description: v0 search filters with deprecated fields.
    LegacyInternalSearchRequest:
      properties:
        query:
          anyOf:
            - type: string
            - type: 'null'
          title: Query
          description: Search query
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
          description: Image URL
        base64_image:
          anyOf:
            - type: string
            - type: 'null'
          title: Base64 Image
          description: Base64 encoded image
        limit:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Limit
          description: Optional limit on the number of results. Default is 20, max is 30.
          default: 20
        filters:
          $ref: '#/components/schemas/LegacyInternalSearchFilters'
          description: >-
            Optional filters. Search will only consider products that match all
            of the filters.
        config:
          $ref: '#/components/schemas/LegacyInternalSearchConfig'
          description: Optional configuration
        context:
          anyOf:
            - type: string
            - type: 'null'
          title: Context
          description: Optional customer information to personalize search results
      additionalProperties: false
      type: object
      title: LegacyInternalSearchRequest
      description: v0 search request (frozen, no pagination).
    LocaleConfig:
      properties:
        language:
          anyOf:
            - type: string
              enum:
                - en
                - de
                - fr
                - it
                - es
                - nl
                - sv
                - fi
                - pt
                - cs
                - el
                - ro
            - type: 'null'
          title: Language
          description: >-
            ISO 639-1 language code. When unset, inferred from ``country``
            (preferred) then ``currency``, defaulting to ``en``.
        country:
          anyOf:
            - type: string
              enum:
                - US
                - GB
                - EU
                - AU
                - CA
                - IE
                - DE
                - AT
                - FR
                - BE
                - IT
                - ES
                - NL
                - SE
                - FI
                - PT
                - CZ
                - GR
                - RO
            - type: 'null'
          title: Country
          description: >-
            ISO 3166-1 alpha-2 country code. May stay unset for pan-region
            storefronts (e.g. ``currency=EUR`` with no specific country).
        currency:
          anyOf:
            - type: string
              enum:
                - USD
                - CAD
                - AUD
                - GBP
                - EUR
                - SEK
                - CZK
                - RON
            - type: 'null'
          title: Currency
          description: >-
            ISO 4217 currency code. When unset, inferred from ``country`` (e.g.
            ``GB`` → ``GBP``), defaulting to ``USD``.
      additionalProperties: false
      type: object
      title: LocaleConfig
      description: >-
        Locale options for API requests.


        Locale fields are optional; the server infers missing values. Details
        are

        on ``language``, ``country``, and ``currency`` below.
    LookupRequest:
      properties:
        url:
          type: string
          title: Url
          description: The URL of the product to look up
        max_staleness_hours:
          type: integer
          minimum: 1
          title: Max Staleness Hours
          description: >-
            Maximum age (in hours) of cached product data before forcing a fresh
            lookup. Defaults to 3 hours.
          default: 3
      additionalProperties: false
      type: object
      required:
        - url
      title: LookupRequest
    LookupResponse:
      properties:
        product:
          $ref: '#/components/schemas/Product'
      type: object
      required:
        - product
      title: LookupResponse
      description: Response from the /v1/lookup endpoint.
    OptionValue:
      properties:
        label:
          type: string
          title: Label
          description: The display value of the option value (e.g. 'Blue')
        exists:
          type: boolean
          title: Exists
          description: >-
            Whether the option value exists on the product, or is a
            configuration only present on another variant of the same product.
            For example, a shirt that comes in multiple colors, but only one
            color is available in Size XL.
        available:
          anyOf:
            - $ref: '#/components/schemas/AvailabilityStatus'
            - type: 'null'
          description: >-
            The availability status of the option value. None when returned on
            search results, hydrated only on get product detail requests.
        thumbnail_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Thumbnail Url
          description: >-
            For options that reference different products, this is the URL of
            the thumbnail image for the option value. E.g., a shoe that comes in
            multiple colors will have an OptionValue for each color with a
            thumbnail_url set.
        product_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Id
          description: >-
            The product id that represents this value. Variants that point to
            different products will have this field set, as well as
            thumbnail_url for displaying selector icons.
      type: object
      required:
        - label
        - exists
      title: OptionValue
      description: One value of one variant option (e.g. 'Blue' under 'Color')
    PaginatedListBrandsResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/Brand'
          type: array
          title: Items
          description: List of brands
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Cursor to fetch the next page of results. Null if no more results.
      type: object
      required:
        - items
      title: PaginatedListBrandsResponse
    PaginatedListCategoriesResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/CategorySummary'
          type: array
          title: Items
          description: Categories in this page
        page:
          type: integer
          title: Page
          description: 1-indexed page number returned
        page_size:
          type: integer
          title: Page Size
          description: Number of items per page
        total:
          type: integer
          title: Total
          description: Total number of categories matching the query
      type: object
      required:
        - items
        - page
        - page_size
        - total
      title: PaginatedListCategoriesResponse
    PaginatedSubscriptionsResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/SubscriptionResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      type: object
      required:
        - items
      title: PaginatedSubscriptionsResponse
    Price:
      properties:
        price:
          type: number
          title: Price
          description: The current price of the product, including any discounts.
        compare_at_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Compare At Price
          description: The original price of the product before any discounts.
        currency:
          type: string
          title: Currency
          description: The currency code of the product, like USD, EUR, GBP, etc.
      type: object
      required:
        - price
        - currency
      title: Price
    PriceHistoryPoint:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        price:
          type: number
          title: Price
        currency:
          type: string
          title: Currency
      type: object
      required:
        - timestamp
        - price
        - currency
      title: PriceHistoryPoint
    PriceHistoryResponse:
      properties:
        canonical_product_id:
          type: string
          title: Canonical Product Id
        product_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Title
        history:
          items:
            $ref: '#/components/schemas/PriceHistoryPoint'
          type: array
          title: History
          default: []
        statistics:
          anyOf:
            - $ref: '#/components/schemas/PriceStatistics'
            - type: 'null'
      type: object
      required:
        - canonical_product_id
      title: PriceHistoryResponse
    PriceStatistics:
      properties:
        mean:
          type: number
          title: Mean
        std_dev:
          type: number
          title: Std Dev
        min_price:
          type: number
          title: Min Price
        max_price:
          type: number
          title: Max Price
        current_price:
          type: number
          title: Current Price
        current_status:
          $ref: '#/components/schemas/PriceStatus'
        currency:
          type: string
          title: Currency
      type: object
      required:
        - mean
        - std_dev
        - min_price
        - max_price
        - current_price
        - current_status
        - currency
      title: PriceStatistics
    PriceStatus:
      type: string
      enum:
        - low
        - typical
        - high
      title: PriceStatus
    Product:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        brands:
          items:
            $ref: '#/components/schemas/ProductBrand'
          type: array
          title: Brands
          description: Ordered list of brands.
        images:
          items:
            $ref: '#/components/schemas/ProductImage'
          type: array
          title: Images
          default: []
        categories:
          items:
            type: string
          type: array
          title: Categories
          deprecated: true
        category:
          anyOf:
            - $ref: '#/components/schemas/CategorySummary'
            - type: 'null'
          description: >-
            The single category this product belongs to, as a structured
            `CategorySummary` (slug, title, path, has_children). Replaces the
            deprecated `categories` field.
        gender:
          anyOf:
            - type: string
              enum:
                - male
                - female
                - unisex
            - type: 'null'
          title: Gender
        age:
          anyOf:
            - type: string
              enum:
                - newborn
                - infant
                - toddler
                - kids
                - adult
            - type: 'null'
          title: Age
          description: >-
            Target age group. Age-agnostic products are typically returned as
            'adult'.
        materials:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Materials
        key_features:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Key Features
        offers:
          items:
            $ref: '#/components/schemas/ProductOffer'
          type: array
          title: Offers
          description: All merchant offers for this product in the requested locale.
        variants:
          anyOf:
            - $ref: '#/components/schemas/Variants'
            - type: 'null'
          description: >-
            Variant interaction state — options, selected. Absent when the
            product has no variations.
        structured_attributes:
          additionalProperties:
            items:
              type: string
            type: array
          type: object
          title: Structured Attributes
          description: >-
            Structured attributes extracted for this product, keyed by attribute
            handle (e.g. 'color', 'material'). Values are the canonical allowed
            values for that handle.
      type: object
      required:
        - id
        - title
      title: Product
      description: Product with detailed information.
    ProductBrand:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
      type: object
      required:
        - id
        - name
      title: ProductBrand
    ProductImage:
      properties:
        url:
          type: string
          title: Url
        is_main_image:
          type: boolean
          title: Is Main Image
          default: false
        is_cleaned_image:
          type: boolean
          title: Is Cleaned Image
          description: >-
            True if this URL points to a cleaned image. A cleaned image has a
            square aspect ratio and a uniform, monochromatic background. Cleaned
            images are best displayed in a product grid.
          default: false
        shot_type:
          anyOf:
            - $ref: '#/components/schemas/ApiProductImageType'
            - type: 'null'
        alt_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Alt Text
      type: object
      required:
        - url
      title: ProductImage
      description: Product image with metadata.
    ProductOffer:
      properties:
        url:
          type: string
          title: Url
        domain:
          type: string
          title: Domain
        price:
          $ref: '#/components/schemas/Price'
        availability:
          type: string
          enum:
            - InStock
            - OutOfStock
          title: Availability
        condition:
          anyOf:
            - type: string
              enum:
                - new
                - refurbished
                - used
            - type: 'null'
          title: Condition
          description: >-
            Condition of this merchant offer (new, used, or refurbished). Null
            when condition is unknown.
        max_commission_rate:
          type: number
          title: Max Commission Rate
          description: >-
            The maximum commission rate for the merchant, as a decimal fraction:
            0 is no commission, 0.5 is 50% commission. 'Max' because the actual
            commission rate may be lower due to vendor-specific affiliate rules.
          default: 0
      type: object
      required:
        - url
        - domain
        - price
        - availability
      title: ProductOffer
    RedirectMode:
      type: string
      enum:
        - brand
        - price
        - commission
      title: RedirectMode
      description: >-
        "price" redirects to the product page with the lowest price

        "commission" redirects to the product page with the highest commission
        rate

        "brand" redirects to the brand's product page
    SearchBrandsResponse:
      properties:
        brands:
          items:
            $ref: '#/components/schemas/Brand'
          type: array
          title: Brands
          description: Brands matching the query, ordered by relevance.
      type: object
      required:
        - brands
      title: SearchBrandsResponse
    SearchCategoriesResponse:
      properties:
        categories:
          items:
            $ref: '#/components/schemas/CategorySummary'
          type: array
          title: Categories
          description: Categories matching the query, ordered by relevance.
      type: object
      required:
        - categories
      title: SearchCategoriesResponse
    SearchColorsFilter:
      properties:
        palette:
          items:
            $ref: '#/components/schemas/SearchFilterColor'
          type: array
          title: Palette
          description: Colors required in matching products. Treated as an AND condition.
      additionalProperties: false
      type: object
      required:
        - palette
      title: SearchColorsFilter
      description: >-
        [Beta] Color filter wrapper. Holds the list of required colors today;

        reserved for future filter-level options (e.g. match modes, tolerance
        overrides).
    SearchConfig:
      properties:
        language:
          anyOf:
            - type: string
              enum:
                - en
                - de
                - fr
                - it
                - es
                - nl
                - sv
                - fi
                - pt
                - cs
                - el
                - ro
            - type: 'null'
          title: Language
          description: >-
            ISO 639-1 language code. When unset, inferred from ``country``
            (preferred) then ``currency``, defaulting to ``en``.
        country:
          anyOf:
            - type: string
              enum:
                - US
                - GB
                - EU
                - AU
                - CA
                - IE
                - DE
                - AT
                - FR
                - BE
                - IT
                - ES
                - NL
                - SE
                - FI
                - PT
                - CZ
                - GR
                - RO
            - type: 'null'
          title: Country
          description: >-
            ISO 3166-1 alpha-2 country code. May stay unset for pan-region
            storefronts (e.g. ``currency=EUR`` with no specific country).
        currency:
          anyOf:
            - type: string
              enum:
                - USD
                - CAD
                - AUD
                - GBP
                - EUR
                - SEK
                - CZK
                - RON
            - type: 'null'
          title: Currency
          description: >-
            ISO 4217 currency code. When unset, inferred from ``country`` (e.g.
            ``GB`` → ``GBP``), defaulting to ``USD``.
        mode:
          $ref: '#/components/schemas/SearchMode'
          description: >-
            Search strategy. `default` (recommended) combines lexical + semantic
            search and is right for most use cases. `keyword` is lexical only —
            use it for real-time, low-latency needs like ad targeting. `agentic`
            uses an LLM to plan multiple structured sub-searches for complex
            queries, with higher latency than the other modes.
          default: default
        keyword_search_only:
          type: boolean
          title: Keyword Search Only
          description: 'Deprecated: use `mode`. `true` is equivalent to `mode=keyword`. '
          default: false
          deprecated: true
      additionalProperties: false
      type: object
      title: SearchConfig
      description: Search and locale options for a search request.
    SearchFilterColor:
      properties:
        hex:
          type: string
          title: Hex
          description: sRGB hex string, e.g. '#a1b2c3'
        percentage:
          anyOf:
            - type: number
            - type: 'null'
          title: Percentage
          description: Percentage of color, where 1.0 is 100%
      type: object
      required:
        - hex
      title: SearchFilterColor
      description: A single color requirement for the color filter.
    SearchFilterPrice:
      properties:
        min_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Min Price
          description: Minimum price, in dollars and cents
        max_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Max Price
          description: Maximum price, in dollars and cents
      additionalProperties: false
      type: object
      title: SearchFilterPrice
      description: Price filter for search. Values are inclusive.
    SearchFilters:
      properties:
        brand_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Brand Ids
          description: If provided, only products from these brands will be returned
        gender:
          anyOf:
            - type: string
              enum:
                - male
                - female
            - type: 'null'
          title: Gender
        condition:
          anyOf:
            - type: string
              enum:
                - new
                - refurbished
                - used
            - type: 'null'
          title: Condition
          description: >-
            Filter by offer condition. Requires at least one offer matching the
            requested condition, locale, and any price filter. Offers without
            condition data are indexed as new.
        age:
          anyOf:
            - items:
                type: string
                enum:
                  - newborn
                  - infant
                  - toddler
                  - kids
                  - adult
              type: array
            - type: 'null'
          title: Age
          description: >-
            Filter by age group. Age-agnostic products are treated as adult
            products.
        price:
          anyOf:
            - $ref: '#/components/schemas/SearchFilterPrice'
            - type: 'null'
          description: If provided, only products within this price range will be returned
        availability:
          anyOf:
            - items:
                $ref: '#/components/schemas/AvailabilityStatus'
              type: array
            - type: 'null'
          title: Availability
          description: >-
            If provided, only products with these availability statuses will be
            returned
        sale:
          anyOf:
            - type: string
              const: on_sale
            - type: 'null'
          title: Sale
          description: >-
            If 'on_sale', only products with at least one on-sale offer (priced
            below its compare-at price) for the requested locale are returned.
            If omitted, no filter.
        website_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Website Ids
          description: >-
            If provided, only products from these websites will be returned.
            Accepts website IDs or domains (e.g. "nike.com").
        category_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Category Ids
          description: >-
            If provided, only products from these categories will be returned.
            Accepts category slugs.
        exclude_brand_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Brand Ids
          description: >-
            If provided, products from these brands will be excluded from the
            results
        exclude_website_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Website Ids
          description: >-
            If provided, products from these websites will be excluded from the
            results. Accepts website IDs or domains (e.g. "nike.com").
        exclude_category_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Category Ids
          description: >-
            If provided, products in these categories (or their descendants)
            will be excluded from the results. Accepts category slugs.
        colors:
          anyOf:
            - $ref: '#/components/schemas/SearchColorsFilter'
            - type: 'null'
          description: >-
            [Beta: filter is experimental and may be changed] If provided, find
            products containing all of these colors.
        attributes:
          anyOf:
            - additionalProperties:
                items:
                  type: string
                type: array
              type: object
            - type: 'null'
          title: Attributes
          description: >-
            If provided, only products whose extracted attributes match these
            key/value constraints will be returned. Keys are attribute handles
            (e.g. 'color', 'material') and values are lists of allowed values
            (OR within a key, AND across keys). When a category filter is also
            supplied, all keys must be valid attributes of at least one of the
            requested categories. See `Category.attributes` for the valid
            keys/values per category.
      additionalProperties: false
      type: object
      title: SearchFilters
      description: Search filters for the search API.
    SearchMode:
      type: string
      enum:
        - keyword
        - default
        - agentic
      title: SearchMode
      description: >-
        Search strategy.


        ``default`` (recommended) combines lexical and semantic search and is
        the

        right choice for most use cases. ``keyword`` runs lexical search only —
        use

        it for real-time, low-latency needs such as ad targeting. ``agentic``
        uses

        an LLM to plan multiple structured sub-searches for complex queries,
        with

        higher latency than the other modes.
    SearchRequest:
      properties:
        query:
          anyOf:
            - type: string
            - type: 'null'
          title: Query
          description: >-
            Search query. At least one of `query`, `image_url`, `base64_image`,
            or `page_token` must be provided.
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
          description: >-
            Image URL. At least one of `query`, `image_url`, `base64_image`, or
            `page_token` must be provided.
        base64_image:
          anyOf:
            - type: string
            - type: 'null'
          title: Base64 Image
          description: >-
            Base64 encoded image. At least one of `query`, `image_url`,
            `base64_image`, or `page_token` must be provided.
        limit:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Limit
          description: Optional limit on the number of results. Default is 20, max is 30.
          default: 20
        filters:
          $ref: '#/components/schemas/SearchFilters'
          description: >-
            Optional filters. Search will only consider products that match all
            of the filters.
          default: {}
        config:
          $ref: '#/components/schemas/SearchConfig'
          description: Optional configuration
          default:
            mode: default
            keyword_search_only: false
        page_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Token
          description: >-
            Opaque token from a previous search response to fetch the next page
            of results.
      additionalProperties: false
      type: object
      title: SearchRequest
      description: Search request with pagination support.
    SearchResponse:
      properties:
        products:
          items:
            $ref: '#/components/schemas/Product'
          type: array
          title: Products
        next_page_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page Token
          description: Token to fetch the next page. Null when no more results.
      type: object
      required:
        - products
      title: SearchResponse
      description: v1 paginated search response.
    SelectedOption:
      properties:
        name:
          type: string
          title: Name
          description: The name of the selected option (e.g. 'Color', 'Size')
        label:
          type: string
          title: Label
          description: The display value of the selected option (e.g. 'Blue', 'XL')
      type: object
      required:
        - name
        - label
      title: SelectedOption
      description: One effective selection on a product, post server-side relaxation.
    SimilarProductsRequest:
      properties:
        product_id:
          type: string
          title: Product Id
          description: Canonical product ID to find similar products for.
        limit:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Limit
          description: Optional limit on the number of results. Default is 20, max is 30.
          default: 20
        filters:
          $ref: '#/components/schemas/SearchFilters'
          description: >-
            Optional filters. Search will only consider products that match all
            of the filters.
          default: {}
        config:
          $ref: '#/components/schemas/LocaleConfig'
          description: Optional locale configuration.
          default: {}
        page_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Token
          description: >-
            Opaque token from a previous similar response to fetch the next page
            of results.
      additionalProperties: false
      type: object
      required:
        - product_id
      title: SimilarProductsRequest
      description: Find products similar to a given product.
    StartTrackingRequest:
      properties:
        canonical_product_id:
          type: string
          title: Canonical Product Id
      type: object
      required:
        - canonical_product_id
      title: StartTrackingRequest
    StopTrackingRequest:
      properties:
        canonical_product_id:
          type: string
          title: Canonical Product Id
      type: object
      required:
        - canonical_product_id
      title: StopTrackingRequest
    SubscriptionResponse:
      properties:
        canonical_product_id:
          type: string
          title: Canonical Product Id
        subscription_status:
          $ref: '#/components/schemas/SubscriptionStatus'
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - canonical_product_id
        - subscription_status
        - created_at
      title: SubscriptionResponse
    SubscriptionStatus:
      type: string
      enum:
        - active
        - cancelled
      title: SubscriptionStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    VariantOption:
      properties:
        name:
          type: string
          title: Name
          description: The name of the option (e.g. 'Color', 'Size')
        values:
          items:
            $ref: '#/components/schemas/OptionValue'
          type: array
          title: Values
          description: The values of the option (e.g. ['Blue', 'Red', 'Green'])
      type: object
      required:
        - name
        - values
      title: VariantOption
      description: One dimension of a product family (e.g. 'Color', 'Size').
    Variants:
      properties:
        options:
          items:
            $ref: '#/components/schemas/VariantOption'
          type: array
          title: Options
        selected:
          items:
            $ref: '#/components/schemas/SelectedOption'
          type: array
          title: Selected
      type: object
      required:
        - options
        - selected
      title: Variants
      description: |-
        Wrapper for variant-interaction state on a Product.

        Holds `options` and `selected`. `options` represent all of the
        configuration options for the product. `selected` represents the
        currently selected option values.
    Website:
      properties:
        id:
          type: string
          title: Id
        url:
          type: string
          title: Url
        best_commission_rate:
          type: number
          title: Best Commission Rate
          description: >-
            The maximum commission rate for the website in the requested country
            (default 'US'), as a percentage
          default: 0
      type: object
      required:
        - id
        - url
      title: Website
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
