openapi: 3.0.3
info:
  title: Pricemind Core API
  description: The public Pricemind Core API contract for channel discovery, complete channel catalog and current selected competitor-offer reads, source inspection and runs, price creation, and tracked crawl requests. Every published operation is available in the API reference. Product reads require products:read; including offers and all offer routes additionally require competitor_prices:read. Catalog pages combine current indexed channel values and available catalog/source data with live multi-request semantics; they do not certify one atomic indexing run or an immutable snapshot. Every /v1 operation requires an API key using X-API-Key or bearer authentication. Protected requests follow the key quota; honor rate-limit headers and Retry-After. Catalog errors use a structured error with code, message, optional details, and X-Request-ID. Existing endpoint contracts remain unchanged. This public snapshot is not an inventory of internal routes.
  version: 1.0.0
  contact:
    name: Pricemind Developer Support
    email: support@pricemind.ai
  license:
    name: Proprietary
    url: https://pricemind.ai/en/terms
  termsOfService: https://pricemind.ai/en/terms
servers:
  - url: https://api.pricemind.io
    description: Production server
  - url: https://staging-api.pricemind.io
    description: Staging server
  - url: http://localhost:8080
    description: Local development server
security:
  - ApiKeyAuth: []
paths:
  /healthz:
    get:
      summary: Health check endpoint
      description: Returns the health status of the API service
      tags:
        - Health
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        "500":
          description: Service is unhealthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: getHealth
      security: []
  /v1/channels:
    get:
      summary: Get available channels for API key
      description: |
        Retrieve channels available for the authenticated API key.

        If the API key is associated with a platform integration (e.g., Magento), 
        this endpoint returns only channels that are connected to that specific integration.

        If the API key is not associated with any integration, it returns all channels 
        owned by the user.

        This endpoint automatically scopes the results based on the API key's integration context,
        making it suitable for both general API usage and platform integrations.
      tags:
        - Channels
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: List of available channels for the API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ChannelDetailed"
                  count:
                    type: integer
                    description: Total number of available channels
                    example: 2
                  next_cursor:
                    type: string
                    nullable: true
                    description: Pagination cursor for next page
                    example: null
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: listChannels
  /v1/channels/{channelId}/prices:
    post:
      summary: Create product price
      description: |
        Create a new price entry for a product in a specific channel.

        This endpoint allows you to set pricing information for products including:
        - Base price
        - Special/discounted price
        - Delivery costs
        - Tax information

        The system will automatically calculate tax-inclusive and tax-exclusive prices based on the provided tax rate.

        After creating a price, the system will trigger an asynchronous reindex operation to update search indexes.
      tags:
        - Prices
      security:
        - ApiKeyAuth: []
      parameters:
        - name: channelId
          in: path
          required: true
          description: The ID of the channel to create the price for
          schema:
            type: integer
            minimum: 1
            example: 123
        - name: channel_source_id
          in: query
          required: false
          description: Specific channel source ID (optional, defaults to active source)
          schema:
            type: integer
            minimum: 1
            example: 456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePriceRequest"
            examples:
              basic_price:
                summary: Basic price creation
                value:
                  product_sku: PROD-12345
                  price: "29.99"
                  currency: USD
                  includes_tax: false
              price_with_tax:
                summary: Price with tax information
                value:
                  product_sku: PROD-12345
                  price: "24.99"
                  currency: EUR
                  includes_tax: true
                  tax_rate: "0.20"
              complete_price:
                summary: Complete price with all fields
                value:
                  product_sku: PROD-12345
                  price: "99.99"
                  special_price: "79.99"
                  delivery_price: "5.99"
                  currency: USD
                  includes_tax: false
                  tax_rate: "0.08"
                  origin: manual
      responses:
        "202":
          description: Price created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/CreatePriceResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Channel or product not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: createPrice
  /v1/channel-sources:
    get:
      operationId: channel_sources.list
      summary: List accessible channel sources (legacy route)
      description: |
        Lists persisted sources available to the authenticated API key. This
        compatibility route remains available to existing legacy credentials.
        New integrations should prefer the channel-scoped source routes. Source
        configuration is deliberately omitted because it may contain credentials
        or authenticated feed URLs.
      tags:
        - Sources
      parameters:
        - name: integration_type
          in: query
          required: false
          description: Restrict sources to one integration type.
          schema:
            type: string
      responses:
        "200":
          description: Accessible persisted sources
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelSourceListEnvelope"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Source lookup failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/channel-sources/{channelSourceId}:
    get:
      operationId: channel_sources.get
      summary: Get an accessible channel source (legacy route)
      description: |
        Returns one persisted source through the legacy account-scoped route.
        Source configuration is deliberately omitted from the response.
      tags:
        - Sources
      parameters:
        - $ref: "#/components/parameters/ChannelSourceId"
      responses:
        "200":
          description: Channel source
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelSourceEnvelope"
        "400":
          description: Invalid channel source ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Channel source not found or inaccessible
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/channels/{channelId}/sources:
    get:
      operationId: channel_sources.list_for_channel
      summary: List channel sources (legacy route)
      description: |
        Lists the persisted sources for an accessible channel. This existing
        compatibility route remains available to legacy credentials. The
        response distinguishes source selection (`selected`) from source-sync
        eligibility (`sync.enabled` and `sync.disabled`).
      tags:
        - Sources
      parameters:
        - $ref: "#/components/parameters/ChannelId"
      responses:
        "200":
          description: Persisted sources for the channel
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelSourceListEnvelope"
        "400":
          description: Invalid channel ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Source lookup failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/channels/{channelId}/sources/active:
    get:
      operationId: channel_sources.get_active
      summary: Get the active channel source (legacy route)
      description: |
        Preserves the existing active-source compatibility route. New clients
        should use `/sources/selected` for the source selected by the channel;
        selection and source-sync enablement are independent states.
      tags:
        - Sources
      parameters:
        - $ref: "#/components/parameters/ChannelId"
      responses:
        "200":
          description: Legacy active source
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelSourceEnvelope"
        "400":
          description: Invalid channel ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Active channel source not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/channels/{channelId}/sources/selected:
    get:
      operationId: channel_sources.get_selected
      summary: Get the source selected for a channel
      description: |
        Returns the source referenced by the channel's `channel_source_id`.
        Requires `sources:read`. This is selection state only: inspect `sync`
        to determine whether source synchronization is enabled and scheduled.
      tags:
        - Sources
      parameters:
        - $ref: "#/components/parameters/ChannelId"
      responses:
        "200":
          description: Selected channel source
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelSourceEnvelope"
        "400":
          $ref: "#/components/responses/SourcePublicError"
        "401":
          $ref: "#/components/responses/SourcePublicError"
        "403":
          $ref: "#/components/responses/SourcePublicError"
        "404":
          $ref: "#/components/responses/SourcePublicError"
        "503":
          $ref: "#/components/responses/SourcePublicError"
  /v1/channels/{channelId}/sources/{channelSourceId}:
    get:
      operationId: channel_sources.get_for_channel
      summary: Get a source in its channel scope
      description: |
        Returns one source only when it belongs to the accessible channel.
        Requires `sources:read`. The response never exposes the source `config`;
        use `selected`, `sync`, and `latest_run` for safe operational state.
      tags:
        - Sources
      parameters:
        - $ref: "#/components/parameters/ChannelId"
        - $ref: "#/components/parameters/ChannelSourceId"
      responses:
        "200":
          description: Channel-scoped source
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelSourceEnvelope"
        "400":
          $ref: "#/components/responses/SourcePublicError"
        "401":
          $ref: "#/components/responses/SourcePublicError"
        "403":
          $ref: "#/components/responses/SourcePublicError"
        "404":
          $ref: "#/components/responses/SourcePublicError"
        "503":
          $ref: "#/components/responses/SourcePublicError"
  /v1/channels/{channelId}/sources/{channelSourceId}/runs:
    post:
      operationId: channel_source_runs.start
      summary: Start a channel source run
      description: |
        Starts an asynchronous manual source synchronization and returns its
        durable numeric dispatch-ledger ID. Requires `sources:run`; legacy API
        keys do not inherit this permission. Manual API runs do not require the
        source to be selected, scheduled, or enabled for scheduled synchronization.
        Runnable source types are `magento`, `shopify`, `senteca`, `feed`, and `file`;
        other source types return `409 source_type_not_runnable`. Poll the returned
        `Location` or use the run-list route for progress.
      tags:
        - Sources
      parameters:
        - $ref: "#/components/parameters/ChannelId"
        - $ref: "#/components/parameters/ChannelSourceId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceRunStartRequest"
      responses:
        "202":
          description: Source run accepted for asynchronous execution
          headers:
            Location:
              description: Channel-scoped URL for the durable source run.
              schema:
                type: string
                example: /v1/channels/123/sources/456/runs/789
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceRunEnvelope"
        "400":
          $ref: "#/components/responses/SourcePublicError"
        "401":
          $ref: "#/components/responses/SourcePublicError"
        "403":
          $ref: "#/components/responses/SourcePublicError"
        "404":
          $ref: "#/components/responses/SourcePublicError"
        "409":
          $ref: "#/components/responses/SourcePublicError"
        "502":
          $ref: "#/components/responses/SourcePublicError"
        "503":
          $ref: "#/components/responses/SourcePublicError"
        "504":
          $ref: "#/components/responses/SourcePublicError"
    get:
      operationId: channel_source_runs.list
      summary: List runs for a channel source
      description: |
        Returns durable source-dispatch runs newest first. Requires
        `sources:read`. Pass the returned `next_cursor` value as the `cursor`
        query parameter to fetch the next page.
      tags:
        - Sources
      parameters:
        - $ref: "#/components/parameters/ChannelId"
        - $ref: "#/components/parameters/ChannelSourceId"
        - name: limit
          in: query
          required: false
          description: Maximum number of runs to return.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          description: Opaque value returned as `next_cursor` by the previous page.
          schema:
            type: string
            maxLength: 2048
      responses:
        "200":
          description: Cursor-paginated source runs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceRunListEnvelope"
        "400":
          $ref: "#/components/responses/SourcePublicError"
        "401":
          $ref: "#/components/responses/SourcePublicError"
        "403":
          $ref: "#/components/responses/SourcePublicError"
        "404":
          $ref: "#/components/responses/SourcePublicError"
        "503":
          $ref: "#/components/responses/SourcePublicError"
  /v1/channels/{channelId}/sources/{channelSourceId}/runs/{sourceRunId}:
    get:
      operationId: channel_source_runs.get
      summary: Get a channel source run
      description: |
        Returns one durable source-dispatch run in its exact channel and source
        scope. Requires `sources:read`. The numeric `source_run_id` identifies
        the dispatch-ledger occurrence and remains stable across retries.
      tags:
        - Sources
      parameters:
        - $ref: "#/components/parameters/ChannelId"
        - $ref: "#/components/parameters/ChannelSourceId"
        - $ref: "#/components/parameters/SourceRunId"
      responses:
        "200":
          description: Source run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceRunEnvelope"
        "400":
          $ref: "#/components/responses/SourcePublicError"
        "401":
          $ref: "#/components/responses/SourcePublicError"
        "403":
          $ref: "#/components/responses/SourcePublicError"
        "404":
          $ref: "#/components/responses/SourcePublicError"
        "503":
          $ref: "#/components/responses/SourcePublicError"
  /v1/channels/{channelId}/crawl-requests:
    post:
      summary: Start a tracked crawl request
      description: |
        Starts an asynchronous crawl for exactly one selector: a single URL,
        a direct batch of at most 100 exact targets, or an authorized saved
        segment snapshotted server-side. Segment snapshots are durably
        idempotent within the authoritative account, channel, and actor scope:
        an exact segment retry reuses one transfer while a changed segment,
        target set, or reason under the same key returns 409. Channel-runner
        separately binds the complete crawl request. Requires the `crawl:run`
        scope. Trusted MCP calls use a server-bound two-step confirmation; this
        schema documents the direct REST write.
      tags:
        - Crawls
      parameters:
        - $ref: "#/components/parameters/ChannelId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CrawlStartRequest"
      responses:
        "200":
          description: Identical idempotent request replayed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CrawlRequestEnvelope"
        "202":
          description: New crawl request accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CrawlRequestEnvelope"
        "400":
          $ref: "#/components/responses/CrawlError"
        "401":
          $ref: "#/components/responses/CrawlError"
        "403":
          $ref: "#/components/responses/CrawlError"
        "404":
          $ref: "#/components/responses/CrawlError"
        "409":
          $ref: "#/components/responses/CrawlError"
        "422":
          $ref: "#/components/responses/CrawlError"
        "429":
          $ref: "#/components/responses/CrawlError"
        "503":
          $ref: "#/components/responses/CrawlError"
      operationId: createCrawlRequest
  /v1/channels/{channelId}/crawl-requests/{requestId}:
    get:
      summary: Get aggregate tracked-crawl progress
      description: Requires the `crawl:read` scope.
      tags:
        - Crawls
      parameters:
        - $ref: "#/components/parameters/ChannelId"
        - $ref: "#/components/parameters/CrawlRequestId"
      responses:
        "200":
          description: Crawl request state and aggregate counts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CrawlRequestEnvelope"
        "400":
          $ref: "#/components/responses/CrawlError"
        "401":
          $ref: "#/components/responses/CrawlError"
        "403":
          $ref: "#/components/responses/CrawlError"
        "404":
          $ref: "#/components/responses/CrawlError"
        "503":
          $ref: "#/components/responses/CrawlError"
      operationId: getCrawlRequest
  /v1/channels/{channelId}/crawl-requests/{requestId}/targets:
    get:
      summary: List per-target tracked-crawl progress and outputs
      description: Requires the `crawl:read` scope.
      tags:
        - Crawls
      parameters:
        - $ref: "#/components/parameters/ChannelId"
        - $ref: "#/components/parameters/CrawlRequestId"
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          schema:
            type: string
            maxLength: 2048
          description: Opaque cursor returned by the previous page.
      responses:
        "200":
          description: Cursor-paginated target progress
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CrawlTargetsEnvelope"
        "400":
          $ref: "#/components/responses/CrawlError"
        "401":
          $ref: "#/components/responses/CrawlError"
        "403":
          $ref: "#/components/responses/CrawlError"
        "404":
          $ref: "#/components/responses/CrawlError"
        "503":
          $ref: "#/components/responses/CrawlError"
      operationId: listCrawlRequestTargets
  /v1/channels/{channel_id}/products:
    get:
      operationId: channel_products.list
      summary: channel products — list
      tags:
        - Channel catalog
      description: Requires products:read. Unknown parameters and repeated scalar parameters are rejected. Filters combine with AND. Complete catalog fields are never truncated or silently skipped. Live pages combine current indexed channel values and available catalog/source data; they do not certify one atomic indexing run or a snapshot across concurrent changes. Exact SKU lookup returns its canonical links.self; none is 404, multiple is 409 ambiguous_sku.
      x-required-scopes:
        - products:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Authorized root account channel.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
          description: "Products without offers and flat offers: default 100/max 500. Products with include=offers: default 25/max 100; 400 outside applicable bounds."
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 8192
          description: Opaque authenticated 24-hour keyset cursor; return unchanged. Filters/includes must match the originating request.
        - name: sku
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Exact case-sensitive own SKU within authorized channel and selected source; preserve punctuation and leading zeroes.
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - offers
          description: Include a complete first OfferPage up to 20 offers per product, with independent continuation. Additionally requires competitor_prices:read.
      responses:
        "200":
          description: Complete existing indexed channel representation with available catalog enrichment; collections may return fewer complete records to respect the 3 MiB serialized JSON budget.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductPage"
              example:
                data:
                  - channel_id: 202
                    catalog:
                      product_domain_id: "12345"
                      sku: ABC/001
                      title: Synthetic example kettle
                      url: https://own.example/products/ABC-001
                      locale: en-GB
                      description:
                        format: html
                        content: <p>Synthetic example description.</p>
                      brand:
                        id: "17"
                        name: Example Brand
                      codes:
                        ean:
                          - "0012345678905"
                        sku:
                          - ABC/001
                        mpn:
                          - K-001
                      categories:
                        - id: "12"
                          name: Kettles
                          path:
                            - Kitchen
                            - Appliances
                            - Kettles
                      images:
                        - url: https://own.example/images/kettle-front.jpg
                          alt: Front view
                          width: 1200
                          height: 1200
                        - url: https://own.example/images/kettle-side.jpg
                          alt: null
                          width: null
                          height: null
                      attributes:
                        - name: capacity
                          label: Capacity
                          data_type: decimal
                          value: "1.500"
                          unit: L
                        - name: features
                          label: null
                          data_type: array
                          value:
                            - quiet
                            - automatic
                          unit: null
                        - name: cordless
                          label: Cordless
                          data_type: boolean
                          value: true
                          unit: null
                      variant:
                        is_configurable: false
                        parent_product_domain_id: null
                        attributes:
                          - name: colour
                            label: Colour
                            data_type: string
                            value: Blue
                            unit: null
                      custom_fields:
                        - machine_name: cost
                          label: Cost
                          data_type: decimal
                          value: "65.000"
                      updated_at: 2026-09-14T08:00:00Z
                      field_status: {}
                    price:
                      currency: EUR
                      regular:
                        excl_tax: "100.00"
                        incl_tax: "120.00"
                      special:
                        excl_tax: "90.00"
                        incl_tax: "108.00"
                      effective:
                        excl_tax: "90.00"
                        incl_tax: "108.00"
                      delivery:
                        excl_tax: null
                        incl_tax: null
                      tax_rate: "0.20"
                      effective_includes_delivery: false
                      product_price_id: "998877"
                      observed_at: 2026-09-14T08:00:00Z
                      stale_at: 2026-09-16T08:00:00Z
                    additional_prices: []
                    availability: 1
                    status: null
                    quality:
                      is_stale: false
                      eligible_for_comparison: true
                      reasons: []
                    links:
                      self: /v1/channels/202/products/12345
                      offers: /v1/channels/202/products/12345/offers
                    offers:
                      data:
                        - offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                          channel_id: 202
                          main_product_domain_id: "12345"
                          competitor:
                            domain: shop.example
                          product:
                            product_domain_id: "67890"
                            sku: SHOP-0001
                            title: Synthetic example kettle
                            url: https://shop.example/product/0001
                            locale: en-GB
                            description:
                              format: null
                              content: <p>Synthetic example description.</p>
                            brand:
                              id: "17"
                              name: Example Brand
                            codes:
                              ean:
                                - "0012345678905"
                              sku:
                                - SHOP-0001
                              mpn:
                                - K-001
                            categories:
                              - id: "12"
                                name: Kettles
                                path:
                                  - Kitchen
                                  - Appliances
                                  - Kettles
                            images:
                              - url: https://shop.example/images/kettle-front.jpg
                                alt: Front view
                                width: 1200
                                height: 1200
                              - url: https://shop.example/images/kettle-side.jpg
                                alt: null
                                width: null
                                height: null
                            attributes:
                              - name: capacity
                                label: Capacity
                                data_type: decimal
                                value: "1.500"
                                unit: L
                              - name: features
                                label: null
                                data_type: array
                                value:
                                  - quiet
                                  - automatic
                                unit: null
                              - name: cordless
                                label: Cordless
                                data_type: boolean
                                value: true
                                unit: null
                            variant:
                              is_configurable: false
                              parent_product_domain_id: null
                              attributes:
                                - name: colour
                                  label: Colour
                                  data_type: string
                                  value: Blue
                                  unit: null
                            custom_fields: []
                            updated_at: 2026-09-14T08:00:00Z
                            field_status: {}
                          url: https://shop.example/buy/0001
                          relationship:
                            kind: primary
                            match_source: both
                            selected_for_comparison: true
                            seller_id: null
                            seller_name: null
                            split_criteria: null
                          price:
                            currency: EUR
                            regular:
                              excl_tax: "100.00"
                              incl_tax: "120.00"
                            special:
                              excl_tax: "90.00"
                              incl_tax: "108.00"
                            effective:
                              excl_tax: "90.00"
                              incl_tax: "108.00"
                            delivery:
                              excl_tax: null
                              incl_tax: null
                            tax_rate: "0.20"
                            effective_includes_delivery: false
                            product_price_id: "998877"
                            observed_at: 2026-09-14T08:00:00Z
                            stale_at: 2026-09-16T08:00:00Z
                          additional_prices:
                            - field_id: "91"
                              name: Trade
                              price:
                                currency: USD
                                regular:
                                  excl_tax: "100.00"
                                  incl_tax: "120.00"
                                special:
                                  excl_tax: "90.00"
                                  incl_tax: "108.00"
                                effective:
                                  excl_tax: "90.00"
                                  incl_tax: "108.00"
                                delivery:
                                  excl_tax: null
                                  incl_tax: null
                                tax_rate: "0.20"
                                effective_includes_delivery: false
                                product_price_id: "998877"
                                observed_at: 2026-09-14T08:00:00Z
                                stale_at: 2026-09-16T08:00:00Z
                          availability: 1
                          status: null
                          quality:
                            is_stale: false
                            eligible_for_comparison: true
                            reasons: []
                          links:
                            self: /v1/channels/202/offers/v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                      pagination:
                        limit: 20
                        has_more: false
                        next_cursor: null
                      links:
                        next: null
                      meta:
                        consistency: live
                        coverage: selected_matched_offers
                pagination:
                  limit: 25
                  has_more: false
                  next_cursor: null
                links:
                  next: null
                meta:
                  consistency: live
                  coverage: channel_products
        "400":
          description: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
        "401":
          description: Invalid or missing credential.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_credential
                  message: Invalid or missing credential.
        "403":
          description: Required explicit scopes are missing.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: insufficient_scope
                  message: Required explicit scopes are missing.
        "404":
          description: Resource absent from the authorized channel/source.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: resource_not_found
                  message: Resource absent from the authorized channel/source.
        "409":
          description: More than one product in this channel has the supplied SKU. source_changed also uses 409.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: ambiguous_sku
                  message: More than one product in this channel has the supplied SKU.
                  details:
                    parameter: sku
        "410":
          description: Cursor expired after 24 hours.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: cursor_expired
                  message: Cursor expired after 24 hours.
        "429":
          description: Credential quota exceeded; observe Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: quota_exceeded
                  message: Credential quota exceeded; observe Retry-After.
        "502":
          description: Invalid or failed upstream response.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_invalid_response
                  message: Invalid or failed upstream response.
        "503":
          description: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: representation_unavailable
                  message: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
                  details:
                    reason: record_too_large
        "504":
          description: Bounded upstream timeout; reads are never silently retried.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: Bounded upstream timeout; reads are never silently retried.
  /v1/channels/{channel_id}/products/{product_domain_id}:
    get:
      operationId: channel_products.get
      summary: channel products — get
      tags:
        - Channel catalog
      description: Requires products:read. Unknown parameters and repeated scalar parameters are rejected. Filters combine with AND. Complete catalog fields are never truncated or silently skipped. Live pages combine current indexed channel values and available catalog/source data; they do not certify one atomic indexing run or a snapshot across concurrent changes. Exact SKU lookup returns its canonical links.self; none is 404, multiple is 409 ambiguous_sku.
      x-required-scopes:
        - products:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Authorized root account channel.
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - offers
          description: Include a complete first OfferPage up to 20 offers per product, with independent continuation. Additionally requires competitor_prices:read.
        - name: product_domain_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
            description: Decimal identity serialized as a string; never a legacy product_id.
        - name: If-None-Match
          in: header
          schema:
            type: string
          description: Representation ETag. Authentication, authoritative scopes and visibility are rechecked before 304.
      responses:
        "200":
          description: Complete existing indexed channel representation with available catalog enrichment; collections may return fewer complete records to respect the 3 MiB serialized JSON budget.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
              description: Hash of the fully computed current representation, including joined catalog/offer data and time-dependent quality. Not a monotonic revision or indexing timestamp; permission checks precede conditional responses.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductEnvelope"
              example:
                data:
                  channel_id: 202
                  catalog:
                    product_domain_id: "12345"
                    sku: ABC/001
                    title: Synthetic example kettle
                    url: https://own.example/products/ABC-001
                    locale: en-GB
                    description:
                      format: html
                      content: <p>Synthetic example description.</p>
                    brand:
                      id: "17"
                      name: Example Brand
                    codes:
                      ean:
                        - "0012345678905"
                      sku:
                        - ABC/001
                      mpn:
                        - K-001
                    categories:
                      - id: "12"
                        name: Kettles
                        path:
                          - Kitchen
                          - Appliances
                          - Kettles
                    images:
                      - url: https://own.example/images/kettle-front.jpg
                        alt: Front view
                        width: 1200
                        height: 1200
                      - url: https://own.example/images/kettle-side.jpg
                        alt: null
                        width: null
                        height: null
                    attributes:
                      - name: capacity
                        label: Capacity
                        data_type: decimal
                        value: "1.500"
                        unit: L
                      - name: features
                        label: null
                        data_type: array
                        value:
                          - quiet
                          - automatic
                        unit: null
                      - name: cordless
                        label: Cordless
                        data_type: boolean
                        value: true
                        unit: null
                    variant:
                      is_configurable: false
                      parent_product_domain_id: null
                      attributes:
                        - name: colour
                          label: Colour
                          data_type: string
                          value: Blue
                          unit: null
                    custom_fields:
                      - machine_name: cost
                        label: Cost
                        data_type: decimal
                        value: "65.000"
                    updated_at: 2026-09-14T08:00:00Z
                    field_status: {}
                  price:
                    currency: EUR
                    regular:
                      excl_tax: "100.00"
                      incl_tax: "120.00"
                    special:
                      excl_tax: "90.00"
                      incl_tax: "108.00"
                    effective:
                      excl_tax: "90.00"
                      incl_tax: "108.00"
                    delivery:
                      excl_tax: null
                      incl_tax: null
                    tax_rate: "0.20"
                    effective_includes_delivery: false
                    product_price_id: "998877"
                    observed_at: 2026-09-14T08:00:00Z
                    stale_at: 2026-09-16T08:00:00Z
                  additional_prices: []
                  availability: 1
                  status: null
                  quality:
                    is_stale: false
                    eligible_for_comparison: true
                    reasons: []
                  links:
                    self: /v1/channels/202/products/12345
                    offers: /v1/channels/202/products/12345/offers
                  offers:
                    data:
                      - offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                        channel_id: 202
                        main_product_domain_id: "12345"
                        competitor:
                          domain: shop.example
                        product:
                          product_domain_id: "67890"
                          sku: SHOP-0001
                          title: Synthetic example kettle
                          url: https://shop.example/product/0001
                          locale: en-GB
                          description:
                            format: null
                            content: <p>Synthetic example description.</p>
                          brand:
                            id: "17"
                            name: Example Brand
                          codes:
                            ean:
                              - "0012345678905"
                            sku:
                              - SHOP-0001
                            mpn:
                              - K-001
                          categories:
                            - id: "12"
                              name: Kettles
                              path:
                                - Kitchen
                                - Appliances
                                - Kettles
                          images:
                            - url: https://shop.example/images/kettle-front.jpg
                              alt: Front view
                              width: 1200
                              height: 1200
                            - url: https://shop.example/images/kettle-side.jpg
                              alt: null
                              width: null
                              height: null
                          attributes:
                            - name: capacity
                              label: Capacity
                              data_type: decimal
                              value: "1.500"
                              unit: L
                            - name: features
                              label: null
                              data_type: array
                              value:
                                - quiet
                                - automatic
                              unit: null
                            - name: cordless
                              label: Cordless
                              data_type: boolean
                              value: true
                              unit: null
                          variant:
                            is_configurable: false
                            parent_product_domain_id: null
                            attributes:
                              - name: colour
                                label: Colour
                                data_type: string
                                value: Blue
                                unit: null
                          custom_fields: []
                          updated_at: 2026-09-14T08:00:00Z
                          field_status: {}
                        url: https://shop.example/buy/0001
                        relationship:
                          kind: primary
                          match_source: both
                          selected_for_comparison: true
                          seller_id: null
                          seller_name: null
                          split_criteria: null
                        price:
                          currency: EUR
                          regular:
                            excl_tax: "100.00"
                            incl_tax: "120.00"
                          special:
                            excl_tax: "90.00"
                            incl_tax: "108.00"
                          effective:
                            excl_tax: "90.00"
                            incl_tax: "108.00"
                          delivery:
                            excl_tax: null
                            incl_tax: null
                          tax_rate: "0.20"
                          effective_includes_delivery: false
                          product_price_id: "998877"
                          observed_at: 2026-09-14T08:00:00Z
                          stale_at: 2026-09-16T08:00:00Z
                        additional_prices:
                          - field_id: "91"
                            name: Trade
                            price:
                              currency: USD
                              regular:
                                excl_tax: "100.00"
                                incl_tax: "120.00"
                              special:
                                excl_tax: "90.00"
                                incl_tax: "108.00"
                              effective:
                                excl_tax: "90.00"
                                incl_tax: "108.00"
                              delivery:
                                excl_tax: null
                                incl_tax: null
                              tax_rate: "0.20"
                              effective_includes_delivery: false
                              product_price_id: "998877"
                              observed_at: 2026-09-14T08:00:00Z
                              stale_at: 2026-09-16T08:00:00Z
                        availability: 1
                        status: null
                        quality:
                          is_stale: false
                          eligible_for_comparison: true
                          reasons: []
                        links:
                          self: /v1/channels/202/offers/v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                    pagination:
                      limit: 20
                      has_more: false
                      next_cursor: null
                    links:
                      next: null
                    meta:
                      consistency: live
                      coverage: selected_matched_offers
        "304":
          description: Authorized representation unchanged; no body.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
        "400":
          description: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
        "401":
          description: Invalid or missing credential.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_credential
                  message: Invalid or missing credential.
        "403":
          description: Required explicit scopes are missing.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: insufficient_scope
                  message: Required explicit scopes are missing.
        "404":
          description: Resource absent from the authorized channel/source.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: resource_not_found
                  message: Resource absent from the authorized channel/source.
        "409":
          description: More than one product in this channel has the supplied SKU. source_changed also uses 409.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: ambiguous_sku
                  message: More than one product in this channel has the supplied SKU.
                  details:
                    parameter: sku
        "410":
          description: Cursor expired after 24 hours.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: cursor_expired
                  message: Cursor expired after 24 hours.
        "429":
          description: Credential quota exceeded; observe Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: quota_exceeded
                  message: Credential quota exceeded; observe Retry-After.
        "502":
          description: Invalid or failed upstream response.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_invalid_response
                  message: Invalid or failed upstream response.
        "503":
          description: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: representation_unavailable
                  message: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
                  details:
                    reason: record_too_large
        "504":
          description: Bounded upstream timeout; reads are never silently retried.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: Bounded upstream timeout; reads are never silently retried.
  /v1/channels/{channel_id}/products/lookup:
    get:
      operationId: channel_products.lookup
      summary: channel products — lookup
      tags:
        - Channel catalog
      description: Requires products:read. Unknown parameters and repeated scalar parameters are rejected. Filters combine with AND. Complete catalog fields are never truncated or silently skipped. Live pages combine current indexed channel values and available catalog/source data; they do not certify one atomic indexing run or a snapshot across concurrent changes. Exact SKU lookup returns its canonical links.self; none is 404, multiple is 409 ambiguous_sku.
      x-required-scopes:
        - products:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Authorized root account channel.
        - name: sku
          in: query
          required: true
          schema:
            type: string
            minLength: 1
          description: Exact case-sensitive own SKU within authorized channel and selected source; preserve punctuation and leading zeroes.
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - offers
          description: Include a complete first OfferPage up to 20 offers per product, with independent continuation. Additionally requires competitor_prices:read.
        - name: If-None-Match
          in: header
          schema:
            type: string
          description: Representation ETag. Authentication, authoritative scopes and visibility are rechecked before 304.
      responses:
        "200":
          description: Complete existing indexed channel representation with available catalog enrichment; collections may return fewer complete records to respect the 3 MiB serialized JSON budget.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
              description: Hash of the fully computed current representation, including joined catalog/offer data and time-dependent quality. Not a monotonic revision or indexing timestamp; permission checks precede conditional responses.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductEnvelope"
              example:
                data:
                  channel_id: 202
                  catalog:
                    product_domain_id: "12345"
                    sku: ABC/001
                    title: Synthetic example kettle
                    url: https://own.example/products/ABC-001
                    locale: en-GB
                    description:
                      format: html
                      content: <p>Synthetic example description.</p>
                    brand:
                      id: "17"
                      name: Example Brand
                    codes:
                      ean:
                        - "0012345678905"
                      sku:
                        - ABC/001
                      mpn:
                        - K-001
                    categories:
                      - id: "12"
                        name: Kettles
                        path:
                          - Kitchen
                          - Appliances
                          - Kettles
                    images:
                      - url: https://own.example/images/kettle-front.jpg
                        alt: Front view
                        width: 1200
                        height: 1200
                      - url: https://own.example/images/kettle-side.jpg
                        alt: null
                        width: null
                        height: null
                    attributes:
                      - name: capacity
                        label: Capacity
                        data_type: decimal
                        value: "1.500"
                        unit: L
                      - name: features
                        label: null
                        data_type: array
                        value:
                          - quiet
                          - automatic
                        unit: null
                      - name: cordless
                        label: Cordless
                        data_type: boolean
                        value: true
                        unit: null
                    variant:
                      is_configurable: false
                      parent_product_domain_id: null
                      attributes:
                        - name: colour
                          label: Colour
                          data_type: string
                          value: Blue
                          unit: null
                    custom_fields:
                      - machine_name: cost
                        label: Cost
                        data_type: decimal
                        value: "65.000"
                    updated_at: 2026-09-14T08:00:00Z
                    field_status: {}
                  price:
                    currency: EUR
                    regular:
                      excl_tax: "100.00"
                      incl_tax: "120.00"
                    special:
                      excl_tax: "90.00"
                      incl_tax: "108.00"
                    effective:
                      excl_tax: "90.00"
                      incl_tax: "108.00"
                    delivery:
                      excl_tax: null
                      incl_tax: null
                    tax_rate: "0.20"
                    effective_includes_delivery: false
                    product_price_id: "998877"
                    observed_at: 2026-09-14T08:00:00Z
                    stale_at: 2026-09-16T08:00:00Z
                  additional_prices: []
                  availability: 1
                  status: null
                  quality:
                    is_stale: false
                    eligible_for_comparison: true
                    reasons: []
                  links:
                    self: /v1/channels/202/products/12345
                    offers: /v1/channels/202/products/12345/offers
                  offers:
                    data:
                      - offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                        channel_id: 202
                        main_product_domain_id: "12345"
                        competitor:
                          domain: shop.example
                        product:
                          product_domain_id: "67890"
                          sku: SHOP-0001
                          title: Synthetic example kettle
                          url: https://shop.example/product/0001
                          locale: en-GB
                          description:
                            format: null
                            content: <p>Synthetic example description.</p>
                          brand:
                            id: "17"
                            name: Example Brand
                          codes:
                            ean:
                              - "0012345678905"
                            sku:
                              - SHOP-0001
                            mpn:
                              - K-001
                          categories:
                            - id: "12"
                              name: Kettles
                              path:
                                - Kitchen
                                - Appliances
                                - Kettles
                          images:
                            - url: https://shop.example/images/kettle-front.jpg
                              alt: Front view
                              width: 1200
                              height: 1200
                            - url: https://shop.example/images/kettle-side.jpg
                              alt: null
                              width: null
                              height: null
                          attributes:
                            - name: capacity
                              label: Capacity
                              data_type: decimal
                              value: "1.500"
                              unit: L
                            - name: features
                              label: null
                              data_type: array
                              value:
                                - quiet
                                - automatic
                              unit: null
                            - name: cordless
                              label: Cordless
                              data_type: boolean
                              value: true
                              unit: null
                          variant:
                            is_configurable: false
                            parent_product_domain_id: null
                            attributes:
                              - name: colour
                                label: Colour
                                data_type: string
                                value: Blue
                                unit: null
                          custom_fields: []
                          updated_at: 2026-09-14T08:00:00Z
                          field_status: {}
                        url: https://shop.example/buy/0001
                        relationship:
                          kind: primary
                          match_source: both
                          selected_for_comparison: true
                          seller_id: null
                          seller_name: null
                          split_criteria: null
                        price:
                          currency: EUR
                          regular:
                            excl_tax: "100.00"
                            incl_tax: "120.00"
                          special:
                            excl_tax: "90.00"
                            incl_tax: "108.00"
                          effective:
                            excl_tax: "90.00"
                            incl_tax: "108.00"
                          delivery:
                            excl_tax: null
                            incl_tax: null
                          tax_rate: "0.20"
                          effective_includes_delivery: false
                          product_price_id: "998877"
                          observed_at: 2026-09-14T08:00:00Z
                          stale_at: 2026-09-16T08:00:00Z
                        additional_prices:
                          - field_id: "91"
                            name: Trade
                            price:
                              currency: USD
                              regular:
                                excl_tax: "100.00"
                                incl_tax: "120.00"
                              special:
                                excl_tax: "90.00"
                                incl_tax: "108.00"
                              effective:
                                excl_tax: "90.00"
                                incl_tax: "108.00"
                              delivery:
                                excl_tax: null
                                incl_tax: null
                              tax_rate: "0.20"
                              effective_includes_delivery: false
                              product_price_id: "998877"
                              observed_at: 2026-09-14T08:00:00Z
                              stale_at: 2026-09-16T08:00:00Z
                        availability: 1
                        status: null
                        quality:
                          is_stale: false
                          eligible_for_comparison: true
                          reasons: []
                        links:
                          self: /v1/channels/202/offers/v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                    pagination:
                      limit: 20
                      has_more: false
                      next_cursor: null
                    links:
                      next: null
                    meta:
                      consistency: live
                      coverage: selected_matched_offers
        "304":
          description: Authorized representation unchanged; no body.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
        "400":
          description: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
        "401":
          description: Invalid or missing credential.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_credential
                  message: Invalid or missing credential.
        "403":
          description: Required explicit scopes are missing.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: insufficient_scope
                  message: Required explicit scopes are missing.
        "404":
          description: Resource absent from the authorized channel/source.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: resource_not_found
                  message: Resource absent from the authorized channel/source.
        "409":
          description: More than one product in this channel has the supplied SKU. source_changed also uses 409.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: ambiguous_sku
                  message: More than one product in this channel has the supplied SKU.
                  details:
                    parameter: sku
        "410":
          description: Cursor expired after 24 hours.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: cursor_expired
                  message: Cursor expired after 24 hours.
        "429":
          description: Credential quota exceeded; observe Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: quota_exceeded
                  message: Credential quota exceeded; observe Retry-After.
        "502":
          description: Invalid or failed upstream response.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_invalid_response
                  message: Invalid or failed upstream response.
        "503":
          description: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: representation_unavailable
                  message: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
                  details:
                    reason: record_too_large
        "504":
          description: Bounded upstream timeout; reads are never silently retried.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: Bounded upstream timeout; reads are never silently retried.
  /v1/channels/{channel_id}/offers:
    get:
      operationId: channel_offers.list
      summary: channel offers — list
      tags:
        - Channel catalog
      description: Requires products:read, competitor_prices:read. Unknown parameters and repeated scalar parameters are rejected. Filters combine with AND. Complete catalog fields are never truncated or silently skipped. Live pages combine current indexed channel values and available catalog/source data; they do not certify one atomic indexing run or a snapshot across concurrent changes. Exact SKU lookup returns its canonical links.self; none is 404, multiple is 409 ambiguous_sku.
      x-required-scopes:
        - products:read
        - competitor_prices:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Authorized root account channel.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
          description: "Products without offers and flat offers: default 100/max 500. Products with include=offers: default 25/max 100; 400 outside applicable bounds."
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 8192
          description: Opaque authenticated 24-hour keyset cursor; return unchanged. Filters/includes must match the originating request.
        - name: main_product_domain_id
          in: query
          required: false
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
            description: Decimal identity serialized as a string; never a legacy product_id.
          description: Own channel product identity; AND with every other filter.
        - name: competitor_product_domain_id
          in: query
          required: false
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
            description: Decimal identity serialized as a string; never a legacy product_id.
          description: Competitor product identity; may select several channel associations.
        - name: competitor_domain
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Exact competitor domain, required with competitor_sku.
        - name: competitor_sku
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Exact competitor SKU, a different identifier from own sku; requires competitor_domain.
      responses:
        "200":
          description: Complete existing indexed channel representation with available catalog enrichment; collections may return fewer complete records to respect the 3 MiB serialized JSON budget.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfferPage"
              example:
                data:
                  - offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                    channel_id: 202
                    main_product_domain_id: "12345"
                    competitor:
                      domain: shop.example
                    product:
                      product_domain_id: "67890"
                      sku: SHOP-0001
                      title: Synthetic example kettle
                      url: https://shop.example/product/0001
                      locale: en-GB
                      description:
                        format: null
                        content: <p>Synthetic example description.</p>
                      brand:
                        id: "17"
                        name: Example Brand
                      codes:
                        ean:
                          - "0012345678905"
                        sku:
                          - SHOP-0001
                        mpn:
                          - K-001
                      categories:
                        - id: "12"
                          name: Kettles
                          path:
                            - Kitchen
                            - Appliances
                            - Kettles
                      images:
                        - url: https://shop.example/images/kettle-front.jpg
                          alt: Front view
                          width: 1200
                          height: 1200
                        - url: https://shop.example/images/kettle-side.jpg
                          alt: null
                          width: null
                          height: null
                      attributes:
                        - name: capacity
                          label: Capacity
                          data_type: decimal
                          value: "1.500"
                          unit: L
                        - name: features
                          label: null
                          data_type: array
                          value:
                            - quiet
                            - automatic
                          unit: null
                        - name: cordless
                          label: Cordless
                          data_type: boolean
                          value: true
                          unit: null
                      variant:
                        is_configurable: false
                        parent_product_domain_id: null
                        attributes:
                          - name: colour
                            label: Colour
                            data_type: string
                            value: Blue
                            unit: null
                      custom_fields: []
                      updated_at: 2026-09-14T08:00:00Z
                      field_status: {}
                    url: https://shop.example/buy/0001
                    relationship:
                      kind: primary
                      match_source: both
                      selected_for_comparison: true
                      seller_id: null
                      seller_name: null
                      split_criteria: null
                    price:
                      currency: EUR
                      regular:
                        excl_tax: "100.00"
                        incl_tax: "120.00"
                      special:
                        excl_tax: "90.00"
                        incl_tax: "108.00"
                      effective:
                        excl_tax: "90.00"
                        incl_tax: "108.00"
                      delivery:
                        excl_tax: null
                        incl_tax: null
                      tax_rate: "0.20"
                      effective_includes_delivery: false
                      product_price_id: "998877"
                      observed_at: 2026-09-14T08:00:00Z
                      stale_at: 2026-09-16T08:00:00Z
                    additional_prices:
                      - field_id: "91"
                        name: Trade
                        price:
                          currency: USD
                          regular:
                            excl_tax: "100.00"
                            incl_tax: "120.00"
                          special:
                            excl_tax: "90.00"
                            incl_tax: "108.00"
                          effective:
                            excl_tax: "90.00"
                            incl_tax: "108.00"
                          delivery:
                            excl_tax: null
                            incl_tax: null
                          tax_rate: "0.20"
                          effective_includes_delivery: false
                          product_price_id: "998877"
                          observed_at: 2026-09-14T08:00:00Z
                          stale_at: 2026-09-16T08:00:00Z
                    availability: 1
                    status: null
                    quality:
                      is_stale: false
                      eligible_for_comparison: true
                      reasons: []
                    links:
                      self: /v1/channels/202/offers/v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                pagination:
                  limit: 100
                  has_more: false
                  next_cursor: null
                links:
                  next: null
                meta:
                  consistency: live
                  coverage: selected_matched_offers
        "400":
          description: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
        "401":
          description: Invalid or missing credential.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_credential
                  message: Invalid or missing credential.
        "403":
          description: Required explicit scopes are missing.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: insufficient_scope
                  message: Required explicit scopes are missing.
        "404":
          description: Resource absent from the authorized channel/source.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: resource_not_found
                  message: Resource absent from the authorized channel/source.
        "409":
          description: More than one product in this channel has the supplied SKU. source_changed also uses 409.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: ambiguous_sku
                  message: More than one product in this channel has the supplied SKU.
                  details:
                    parameter: sku
        "410":
          description: Cursor expired after 24 hours.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: cursor_expired
                  message: Cursor expired after 24 hours.
        "429":
          description: Credential quota exceeded; observe Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: quota_exceeded
                  message: Credential quota exceeded; observe Retry-After.
        "502":
          description: Invalid or failed upstream response.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_invalid_response
                  message: Invalid or failed upstream response.
        "503":
          description: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: representation_unavailable
                  message: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
                  details:
                    reason: record_too_large
        "504":
          description: Bounded upstream timeout; reads are never silently retried.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: Bounded upstream timeout; reads are never silently retried.
  /v1/channels/{channel_id}/products/{product_domain_id}/offers:
    get:
      operationId: channel_product_offers.list
      summary: channel product offers — list
      tags:
        - Channel catalog
      description: Requires products:read, competitor_prices:read. Unknown parameters and repeated scalar parameters are rejected. Filters combine with AND. Complete catalog fields are never truncated or silently skipped. Live pages combine current indexed channel values and available catalog/source data; they do not certify one atomic indexing run or a snapshot across concurrent changes. Exact SKU lookup returns its canonical links.self; none is 404, multiple is 409 ambiguous_sku.
      x-required-scopes:
        - products:read
        - competitor_prices:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Authorized root account channel.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
          description: "Products without offers and flat offers: default 100/max 500. Products with include=offers: default 25/max 100; 400 outside applicable bounds."
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 8192
          description: Opaque authenticated 24-hour keyset cursor; return unchanged. Filters/includes must match the originating request.
        - name: competitor_product_domain_id
          in: query
          required: false
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
            description: Decimal identity serialized as a string; never a legacy product_id.
          description: Competitor product identity; may select several channel associations.
        - name: competitor_domain
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Exact competitor domain, required with competitor_sku.
        - name: competitor_sku
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Exact competitor SKU, a different identifier from own sku; requires competitor_domain.
        - name: product_domain_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
            description: Decimal identity serialized as a string; never a legacy product_id.
      responses:
        "200":
          description: Complete existing indexed channel representation with available catalog enrichment; collections may return fewer complete records to respect the 3 MiB serialized JSON budget.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfferPage"
              example:
                data:
                  - offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                    channel_id: 202
                    main_product_domain_id: "12345"
                    competitor:
                      domain: shop.example
                    product:
                      product_domain_id: "67890"
                      sku: SHOP-0001
                      title: Synthetic example kettle
                      url: https://shop.example/product/0001
                      locale: en-GB
                      description:
                        format: null
                        content: <p>Synthetic example description.</p>
                      brand:
                        id: "17"
                        name: Example Brand
                      codes:
                        ean:
                          - "0012345678905"
                        sku:
                          - SHOP-0001
                        mpn:
                          - K-001
                      categories:
                        - id: "12"
                          name: Kettles
                          path:
                            - Kitchen
                            - Appliances
                            - Kettles
                      images:
                        - url: https://shop.example/images/kettle-front.jpg
                          alt: Front view
                          width: 1200
                          height: 1200
                        - url: https://shop.example/images/kettle-side.jpg
                          alt: null
                          width: null
                          height: null
                      attributes:
                        - name: capacity
                          label: Capacity
                          data_type: decimal
                          value: "1.500"
                          unit: L
                        - name: features
                          label: null
                          data_type: array
                          value:
                            - quiet
                            - automatic
                          unit: null
                        - name: cordless
                          label: Cordless
                          data_type: boolean
                          value: true
                          unit: null
                      variant:
                        is_configurable: false
                        parent_product_domain_id: null
                        attributes:
                          - name: colour
                            label: Colour
                            data_type: string
                            value: Blue
                            unit: null
                      custom_fields: []
                      updated_at: 2026-09-14T08:00:00Z
                      field_status: {}
                    url: https://shop.example/buy/0001
                    relationship:
                      kind: primary
                      match_source: both
                      selected_for_comparison: true
                      seller_id: null
                      seller_name: null
                      split_criteria: null
                    price:
                      currency: EUR
                      regular:
                        excl_tax: "100.00"
                        incl_tax: "120.00"
                      special:
                        excl_tax: "90.00"
                        incl_tax: "108.00"
                      effective:
                        excl_tax: "90.00"
                        incl_tax: "108.00"
                      delivery:
                        excl_tax: null
                        incl_tax: null
                      tax_rate: "0.20"
                      effective_includes_delivery: false
                      product_price_id: "998877"
                      observed_at: 2026-09-14T08:00:00Z
                      stale_at: 2026-09-16T08:00:00Z
                    additional_prices:
                      - field_id: "91"
                        name: Trade
                        price:
                          currency: USD
                          regular:
                            excl_tax: "100.00"
                            incl_tax: "120.00"
                          special:
                            excl_tax: "90.00"
                            incl_tax: "108.00"
                          effective:
                            excl_tax: "90.00"
                            incl_tax: "108.00"
                          delivery:
                            excl_tax: null
                            incl_tax: null
                          tax_rate: "0.20"
                          effective_includes_delivery: false
                          product_price_id: "998877"
                          observed_at: 2026-09-14T08:00:00Z
                          stale_at: 2026-09-16T08:00:00Z
                    availability: 1
                    status: null
                    quality:
                      is_stale: false
                      eligible_for_comparison: true
                      reasons: []
                    links:
                      self: /v1/channels/202/offers/v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                pagination:
                  limit: 100
                  has_more: false
                  next_cursor: null
                links:
                  next: null
                meta:
                  consistency: live
                  coverage: selected_matched_offers
        "400":
          description: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
        "401":
          description: Invalid or missing credential.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_credential
                  message: Invalid or missing credential.
        "403":
          description: Required explicit scopes are missing.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: insufficient_scope
                  message: Required explicit scopes are missing.
        "404":
          description: Resource absent from the authorized channel/source.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: resource_not_found
                  message: Resource absent from the authorized channel/source.
        "409":
          description: More than one product in this channel has the supplied SKU. source_changed also uses 409.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: ambiguous_sku
                  message: More than one product in this channel has the supplied SKU.
                  details:
                    parameter: sku
        "410":
          description: Cursor expired after 24 hours.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: cursor_expired
                  message: Cursor expired after 24 hours.
        "429":
          description: Credential quota exceeded; observe Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: quota_exceeded
                  message: Credential quota exceeded; observe Retry-After.
        "502":
          description: Invalid or failed upstream response.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_invalid_response
                  message: Invalid or failed upstream response.
        "503":
          description: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: representation_unavailable
                  message: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
                  details:
                    reason: record_too_large
        "504":
          description: Bounded upstream timeout; reads are never silently retried.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: Bounded upstream timeout; reads are never silently retried.
  /v1/channels/{channel_id}/offers/{offer_id}:
    get:
      operationId: channel_offers.get
      summary: channel offers — get
      tags:
        - Channel catalog
      description: Requires products:read, competitor_prices:read. Unknown parameters and repeated scalar parameters are rejected. Filters combine with AND. Complete catalog fields are never truncated or silently skipped. Live pages combine current indexed channel values and available catalog/source data; they do not certify one atomic indexing run or a snapshot across concurrent changes. Exact SKU lookup returns its canonical links.self; none is 404, multiple is 409 ambiguous_sku.
      x-required-scopes:
        - products:read
        - competitor_prices:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Authorized root account channel.
        - name: offer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^v1\.[A-Za-z0-9_-]+$
            description: Versioned opaque logical association ID. Stable across replacement price rows; not an authorization token.
        - name: If-None-Match
          in: header
          schema:
            type: string
          description: Representation ETag. Authentication, authoritative scopes and visibility are rechecked before 304.
      responses:
        "200":
          description: Complete existing indexed channel representation with available catalog enrichment; collections may return fewer complete records to respect the 3 MiB serialized JSON budget.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
              description: Hash of the fully computed current representation, including joined catalog/offer data and time-dependent quality. Not a monotonic revision or indexing timestamp; permission checks precede conditional responses.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfferEnvelope"
              example:
                data:
                  offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                  channel_id: 202
                  main_product_domain_id: "12345"
                  competitor:
                    domain: shop.example
                  product:
                    product_domain_id: "67890"
                    sku: SHOP-0001
                    title: Synthetic example kettle
                    url: https://shop.example/product/0001
                    locale: en-GB
                    description:
                      format: null
                      content: <p>Synthetic example description.</p>
                    brand:
                      id: "17"
                      name: Example Brand
                    codes:
                      ean:
                        - "0012345678905"
                      sku:
                        - SHOP-0001
                      mpn:
                        - K-001
                    categories:
                      - id: "12"
                        name: Kettles
                        path:
                          - Kitchen
                          - Appliances
                          - Kettles
                    images:
                      - url: https://shop.example/images/kettle-front.jpg
                        alt: Front view
                        width: 1200
                        height: 1200
                      - url: https://shop.example/images/kettle-side.jpg
                        alt: null
                        width: null
                        height: null
                    attributes:
                      - name: capacity
                        label: Capacity
                        data_type: decimal
                        value: "1.500"
                        unit: L
                      - name: features
                        label: null
                        data_type: array
                        value:
                          - quiet
                          - automatic
                        unit: null
                      - name: cordless
                        label: Cordless
                        data_type: boolean
                        value: true
                        unit: null
                    variant:
                      is_configurable: false
                      parent_product_domain_id: null
                      attributes:
                        - name: colour
                          label: Colour
                          data_type: string
                          value: Blue
                          unit: null
                    custom_fields: []
                    updated_at: 2026-09-14T08:00:00Z
                    field_status: {}
                  url: https://shop.example/buy/0001
                  relationship:
                    kind: primary
                    match_source: both
                    selected_for_comparison: true
                    seller_id: null
                    seller_name: null
                    split_criteria: null
                  price:
                    currency: EUR
                    regular:
                      excl_tax: "100.00"
                      incl_tax: "120.00"
                    special:
                      excl_tax: "90.00"
                      incl_tax: "108.00"
                    effective:
                      excl_tax: "90.00"
                      incl_tax: "108.00"
                    delivery:
                      excl_tax: null
                      incl_tax: null
                    tax_rate: "0.20"
                    effective_includes_delivery: false
                    product_price_id: "998877"
                    observed_at: 2026-09-14T08:00:00Z
                    stale_at: 2026-09-16T08:00:00Z
                  additional_prices:
                    - field_id: "91"
                      name: Trade
                      price:
                        currency: USD
                        regular:
                          excl_tax: "100.00"
                          incl_tax: "120.00"
                        special:
                          excl_tax: "90.00"
                          incl_tax: "108.00"
                        effective:
                          excl_tax: "90.00"
                          incl_tax: "108.00"
                        delivery:
                          excl_tax: null
                          incl_tax: null
                        tax_rate: "0.20"
                        effective_includes_delivery: false
                        product_price_id: "998877"
                        observed_at: 2026-09-14T08:00:00Z
                        stale_at: 2026-09-16T08:00:00Z
                  availability: 1
                  status: null
                  quality:
                    is_stale: false
                    eligible_for_comparison: true
                    reasons: []
                  links:
                    self: /v1/channels/202/offers/v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
        "304":
          description: Authorized representation unchanged; no body.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
        "400":
          description: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Invalid input, unknown/repeated parameters, unsupported include, malformed IDs or invalid/mismatched cursor.
        "401":
          description: Invalid or missing credential.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_credential
                  message: Invalid or missing credential.
        "403":
          description: Required explicit scopes are missing.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: insufficient_scope
                  message: Required explicit scopes are missing.
        "404":
          description: Resource absent from the authorized channel/source.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: resource_not_found
                  message: Resource absent from the authorized channel/source.
        "409":
          description: More than one product in this channel has the supplied SKU. source_changed also uses 409.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: ambiguous_sku
                  message: More than one product in this channel has the supplied SKU.
                  details:
                    parameter: sku
        "410":
          description: Cursor expired after 24 hours.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: cursor_expired
                  message: Cursor expired after 24 hours.
        "429":
          description: Credential quota exceeded; observe Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: quota_exceeded
                  message: Credential quota exceeded; observe Retry-After.
        "502":
          description: Invalid or failed upstream response.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_invalid_response
                  message: Invalid or failed upstream response.
        "503":
          description: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: representation_unavailable
                  message: Required complete representation unavailable; record_too_large when a full resource exceeds 3 MiB.
                  details:
                    reason: record_too_large
        "504":
          description: Bounded upstream timeout; reads are never silently retried.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: Bounded upstream timeout; reads are never silently retried.
  /v1/extension/tracked-domains:
    get:
      operationId: extension.tracked_domains.list
      summary: Shops your channels track
      tags:
        - Browser companion
      description: Own and competitor shop domains per channel, for deciding which pages to look up at all. Cache it and revalidate with If-None-Match; the list changes when competitors are added or removed. Requires channels:read.
      x-required-scopes:
        - channels:read
      parameters:
        - name: If-None-Match
          in: header
          schema:
            type: string
          description: ETag of a previous response; 304 when the representation is unchanged.
      responses:
        "200":
          description: Shops your channels track
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
              description: Hash of the complete current representation. Send it as If-None-Match; authentication, scopes and channel access are rechecked before 304.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtensionTrackedDomains"
              example:
                - channel_id: 202
                  name: Volta BG
                  currency: EUR
                  own_domains:
                    - own.example
                  competitors:
                    - channel_competitor_id: 3101
                      domain: market.example
                      status: active
                    - channel_competitor_id: 3102
                      domain: shop.example
                      status: active
                - channel_id: 203
                  name: Volta RO
                  currency: RON
                  own_domains:
                    - own.ro
                  competitors:
                    - channel_competitor_id: 3201
                      domain: shop.example
                      status: issues
        "304":
          description: Unchanged since the supplied ETag; no body.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
        "400":
          description: Unknown or repeated parameter, or an invalid value; details.parameter names it.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Unknown or repeated parameter, or an invalid value; details.parameter names it.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The credential lacks a required scope; subject_inactive when the person it belongs to was removed or deactivated in the account.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: insufficient_scope
                  message: The credential lacks a required scope; subject_inactive when the person it belongs to was removed or deactivated in the account.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
  /v1/extension/resolve:
    get:
      operationId: extension.resolve
      summary: Resolve a page URL to your products
      tags:
        - Browser companion
      description: "Finds which of your products a shop page belongs to across every channel of the account: your own product page, a matched competitor page (including marketplace pages and seller listings), a known page that is not matched yet, or an unknown page. Lookups use the page URL and its common variants (trailing slash, query, language prefix, www) and the shop's product-code fingerprint. Pages of shops none of your channels tracks are never looked up and return not_tracked. Requires products:read."
      x-required-scopes:
        - products:read
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            maxLength: 2048
          description: The page URL (http or https; a missing scheme means https). At most 2,048 characters.
        - name: include
          in: query
          required: false
          schema:
            type: string
            pattern: ^(offers|rule)(,(offers|rule))?$
          description: "Comma-separated: offers embeds each match's first OfferPage in main_product.offers (additionally requires competitor_prices:read); rule adds each match's rule suggestion (additionally requires rule_suggestions:read)."
        - name: If-None-Match
          in: header
          schema:
            type: string
          description: ETag of a previous response; 304 when the representation is unchanged.
      responses:
        "200":
          description: Resolve a page URL to your products
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
              description: Hash of the complete current representation. Send it as If-None-Match; authentication, scopes and channel access are rechecked before 304.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtensionResolve"
              example:
                domain: shop.example
                viewed_as: competitor
                matches:
                  - channel_id: 202
                    main_product:
                      channel_id: 202
                      catalog:
                        product_domain_id: "12345"
                        sku: ABC/001
                        title: Synthetic example kettle
                        url: https://own.example/products/ABC-001
                        locale: en-GB
                        description:
                          format: html
                          content: <p>Synthetic example description.</p>
                        brand:
                          id: "17"
                          name: Example Brand
                        codes:
                          ean:
                            - "0012345678905"
                          sku:
                            - ABC/001
                          mpn:
                            - K-001
                        categories:
                          - id: "12"
                            name: Kettles
                            path:
                              - Kitchen
                              - Appliances
                              - Kettles
                        images:
                          - url: https://own.example/images/kettle-front.jpg
                            alt: Front view
                            width: 1200
                            height: 1200
                          - url: https://own.example/images/kettle-side.jpg
                            alt: null
                            width: null
                            height: null
                        attributes:
                          - name: capacity
                            label: Capacity
                            data_type: decimal
                            value: "1.500"
                            unit: L
                          - name: features
                            label: null
                            data_type: array
                            value:
                              - quiet
                              - automatic
                            unit: null
                          - name: cordless
                            label: Cordless
                            data_type: boolean
                            value: true
                            unit: null
                        variant:
                          is_configurable: false
                          parent_product_domain_id: null
                          attributes:
                            - name: colour
                              label: Colour
                              data_type: string
                              value: Blue
                              unit: null
                        custom_fields:
                          - machine_name: cost
                            label: Cost
                            data_type: decimal
                            value: "65.000"
                        updated_at: 2026-09-14T08:00:00Z
                        field_status: {}
                      price:
                        currency: EUR
                        regular:
                          excl_tax: "100.00"
                          incl_tax: "120.00"
                        special:
                          excl_tax: "90.00"
                          incl_tax: "108.00"
                        effective:
                          excl_tax: "90.00"
                          incl_tax: "108.00"
                        delivery:
                          excl_tax: null
                          incl_tax: null
                        tax_rate: "0.20"
                        effective_includes_delivery: false
                        product_price_id: "998877"
                        observed_at: 2026-09-14T08:00:00Z
                        stale_at: 2026-09-16T08:00:00Z
                      additional_prices: []
                      availability: 1
                      status: null
                      quality:
                        is_stale: false
                        eligible_for_comparison: true
                        reasons: []
                      links:
                        self: /v1/channels/202/products/12345
                        offers: /v1/channels/202/products/12345/offers
                      offers:
                        data:
                          - offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                            channel_id: 202
                            main_product_domain_id: "12345"
                            competitor:
                              domain: shop.example
                            product:
                              product_domain_id: "67890"
                              sku: SHOP-0001
                              title: Synthetic example kettle
                              url: https://shop.example/product/0001
                              locale: en-GB
                              description:
                                format: null
                                content: <p>Synthetic example description.</p>
                              brand:
                                id: "17"
                                name: Example Brand
                              codes:
                                ean:
                                  - "0012345678905"
                                sku:
                                  - SHOP-0001
                                mpn:
                                  - K-001
                              categories:
                                - id: "12"
                                  name: Kettles
                                  path:
                                    - Kitchen
                                    - Appliances
                                    - Kettles
                              images:
                                - url: https://shop.example/images/kettle-front.jpg
                                  alt: Front view
                                  width: 1200
                                  height: 1200
                                - url: https://shop.example/images/kettle-side.jpg
                                  alt: null
                                  width: null
                                  height: null
                              attributes:
                                - name: capacity
                                  label: Capacity
                                  data_type: decimal
                                  value: "1.500"
                                  unit: L
                                - name: features
                                  label: null
                                  data_type: array
                                  value:
                                    - quiet
                                    - automatic
                                  unit: null
                                - name: cordless
                                  label: Cordless
                                  data_type: boolean
                                  value: true
                                  unit: null
                              variant:
                                is_configurable: false
                                parent_product_domain_id: null
                                attributes:
                                  - name: colour
                                    label: Colour
                                    data_type: string
                                    value: Blue
                                    unit: null
                              custom_fields: []
                              updated_at: 2026-09-14T08:00:00Z
                              field_status: {}
                            url: https://shop.example/buy/0001
                            relationship:
                              kind: primary
                              match_source: both
                              selected_for_comparison: true
                              seller_id: null
                              seller_name: null
                              split_criteria: null
                            price:
                              currency: EUR
                              regular:
                                excl_tax: "100.00"
                                incl_tax: "120.00"
                              special:
                                excl_tax: "90.00"
                                incl_tax: "108.00"
                              effective:
                                excl_tax: "90.00"
                                incl_tax: "108.00"
                              delivery:
                                excl_tax: null
                                incl_tax: null
                              tax_rate: "0.20"
                              effective_includes_delivery: false
                              product_price_id: "998877"
                              observed_at: 2026-09-14T08:00:00Z
                              stale_at: 2026-09-16T08:00:00Z
                            additional_prices:
                              - field_id: "91"
                                name: Trade
                                price:
                                  currency: USD
                                  regular:
                                    excl_tax: "100.00"
                                    incl_tax: "120.00"
                                  special:
                                    excl_tax: "90.00"
                                    incl_tax: "108.00"
                                  effective:
                                    excl_tax: "90.00"
                                    incl_tax: "108.00"
                                  delivery:
                                    excl_tax: null
                                    incl_tax: null
                                  tax_rate: "0.20"
                                  effective_includes_delivery: false
                                  product_price_id: "998877"
                                  observed_at: 2026-09-14T08:00:00Z
                                  stale_at: 2026-09-16T08:00:00Z
                            availability: 1
                            status: null
                            quality:
                              is_stale: false
                              eligible_for_comparison: true
                              reasons: []
                            links:
                              self: /v1/channels/202/offers/v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                        pagination:
                          limit: 20
                          has_more: false
                          next_cursor: null
                        links:
                          next: null
                        meta:
                          consistency: live
                          coverage: selected_matched_offers
                    competitor_product_domain_id: "67890"
                    channel_competitor_id: 3102
                    match_source: both
                    rule:
                      rule:
                        id: 8
                        name: Match the cheapest
                        execution_mode: scheduled
                        next_execution_at: 2026-10-17T06:00:00Z
                      result:
                        id: 49654833
                        status: pending_approval
                        price_incl: "435.00"
                        price_excl: "362.50"
                        currency: EUR
                        original_price_incl: "449.00"
                        is_approved: false
                        approval_reason: above_auto_approve_range
                        min_price_applied: true
                        min_price_value: "362.50"
                        max_price_applied: false
                        max_price_value: null
                        status_message: null
                        created_at: 2026-10-16T08:43:18Z
                      excluded_reason: null
                trackable_channels:
                  - channel_id: 203
                    channel_competitor_id: 3201
                page: null
        "304":
          description: Unchanged since the supplied ETag; no body.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
        "400":
          description: The page URL is not a valid http(s) URL. url_too_long when it is over 2,048 characters; invalid_input for other parameters.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_url
                  message: The page URL is not a valid http(s) URL. url_too_long when it is over 2,048 characters; invalid_input for other parameters.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The credential lacks a required scope; subject_inactive when the person it belongs to was removed or deactivated in the account.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: insufficient_scope
                  message: The credential lacks a required scope; subject_inactive when the person it belongs to was removed or deactivated in the account.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
  /v1/channels/{channel_id}/products/{product_domain_id}/offers/{competitor_product_domain_id}/history:
    get:
      operationId: channel_offer_history.get
      summary: Recent prices of one offer
      tags:
        - Browser companion
      description: The observed prices of one matched competitor page of your product over the last days (30 by default), in the channel currency. Requires products:read, competitor_prices:read.
      x-required-scopes:
        - products:read
        - competitor_prices:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: A channel of the credential's account.
        - name: product_domain_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
            description: Decimal identity serialized as a string; never a legacy product_id.
          description: Your channel product.
        - name: competitor_product_domain_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
            description: Decimal identity serialized as a string; never a legacy product_id.
          description: The matched competitor page (offer product.product_domain_id).
        - name: days
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 30
            default: 30
          description: Days back from today (UTC).
        - name: If-None-Match
          in: header
          schema:
            type: string
          description: ETag of a previous response; 304 when the representation is unchanged.
      responses:
        "200":
          description: Recent prices of one offer
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
              description: Hash of the complete current representation. Send it as If-None-Match; authentication, scopes and channel access are rechecked before 304.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfferHistory"
              example:
                period_days: 30
                currency: EUR
                points:
                  - date: 2026-09-20T08:00:00Z
                    price: "120.00"
                  - date: 2026-10-01T08:00:00Z
                    price: "108.00"
        "304":
          description: Unchanged since the supplied ETag; no body.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
        "400":
          description: Unknown or repeated parameter, or an invalid value; details.parameter names it.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Unknown or repeated parameter, or an invalid value; details.parameter names it.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: channel_access_denied
                  message: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
        "404":
          description: The page is not a matched offer of this product; product_not_found when the product is not in the channel.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: offer_not_found
                  message: The page is not a matched offer of this product; product_not_found when the product is not in the channel.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
  /v1/channels/{channel_id}/products/{product_domain_id}/rule-suggestion:
    get:
      operationId: channel_rule_suggestion.get
      summary: What your pricing rule will do
      tags:
        - Browser companion
      description: "The pricing rule result that decides this product's price: the suggested price, whether it waits for approval, floor or ceiling hits, and when the rule runs next; or why no rule sets the price. Requires products:read, rule_suggestions:read."
      x-required-scopes:
        - products:read
        - rule_suggestions:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: A channel of the credential's account.
        - name: product_domain_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
            description: Decimal identity serialized as a string; never a legacy product_id.
          description: Your channel product.
        - name: If-None-Match
          in: header
          schema:
            type: string
          description: ETag of a previous response; 304 when the representation is unchanged.
      responses:
        "200":
          description: What your pricing rule will do
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
              description: Hash of the complete current representation. Send it as If-None-Match; authentication, scopes and channel access are rechecked before 304.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuleSuggestion"
              example:
                rule:
                  id: 8
                  name: Match the cheapest
                  execution_mode: scheduled
                  next_execution_at: 2026-10-17T06:00:00Z
                result:
                  id: 49654833
                  status: pending_approval
                  price_incl: "435.00"
                  price_excl: "362.50"
                  currency: EUR
                  original_price_incl: "449.00"
                  is_approved: false
                  approval_reason: above_auto_approve_range
                  min_price_applied: true
                  min_price_value: "362.50"
                  max_price_applied: false
                  max_price_value: null
                  status_message: null
                  created_at: 2026-10-16T08:43:18Z
                excluded_reason: null
        "304":
          description: Unchanged since the supplied ETag; no body.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
        "400":
          description: Unknown or repeated parameter, or an invalid value; details.parameter names it.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Unknown or repeated parameter, or an invalid value; details.parameter names it.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: channel_access_denied
                  message: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
        "404":
          description: The product is not in this channel.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: product_not_found
                  message: The product is not in this channel.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
  /v1/channels/{channel_id}/products/search:
    get:
      operationId: channel_products.search
      summary: Find one of your products
      tags:
        - Browser companion
      description: Search the channel's products by name, SKU, EAN or custom field, to pick the product a competitor page belongs to. Requires products:read.
      x-required-scopes:
        - products:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: A channel of the credential's account.
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 3
          description: At least 3 characters.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 8
          description: Most results to return.
      responses:
        "200":
          description: Find one of your products
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductSearchResults"
              example:
                - product_domain_id: "12345"
                  title: Synthetic example kettle
                  sku: ABC/001
                  ean: "0012345678905"
                  price: "108.00"
                  currency: EUR
        "400":
          description: q has fewer than 3 characters; invalid_input for other parameters.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: query_too_short
                  message: q has fewer than 3 characters; invalid_input for other parameters.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The credential lacks a required scope; subject_inactive when the person it belongs to was removed or deactivated in the account.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: insufficient_scope
                  message: The credential lacks a required scope; subject_inactive when the person it belongs to was removed or deactivated in the account.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
  /v1/channels/{channel_id}/manual-url-requests:
    post:
      operationId: manual_url_requests.start
      summary: Check a competitor page for your product
      tags:
        - Browser companion
      description: "Starts Lobe's manual URL check: Pricemind reads the live page (or reuses a price that is still fresh), then waits for a person to confirm the match. Poll the status until can_confirm, terminal or failure. Starting the same page for the same product again resumes the existing check. Requires products:read, product_pages:write."
      x-required-scopes:
        - products:read
        - product_pages:write
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: A channel of the credential's account.
      responses:
        "202":
          description: Check a competitor page for your product
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManualUrlWorkflow"
              example:
                id: 3f6c1d2e-8a4b-4c5d-9e7f-0a1b2c3d4e5f
                state: ready_for_review
                version: 3
                submitted_url: https://shop.example/product/0001
                preview:
                  product_domain_id: 67890
                  title: Synthetic example kettle
                  url: https://shop.example/product/0001
                  domain: shop.example
                  image: https://shop.example/images/0001.jpg
                  codes:
                    - name: EAN
                      value: "0012345678905"
                  brand: Example Brand
                  price: "99.00"
                  currency: EUR
                  availability: 1
                  observed_at: 2026-10-16T08:00:00Z
                  code_matches:
                    - EAN
                headline: Product ready — your turn
                detail: Check this is the right product, then confirm the match.
                progress: 88
                can_confirm: true
                can_retry: false
                terminal: false
                in_progress: false
                failure: null
        "400":
          description: The page URL is not a valid http(s) URL; url_too_long over 2,048 characters; invalid_input for other fields.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_url
                  message: The page URL is not a valid http(s) URL; url_too_long over 2,048 characters; invalid_input for other fields.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: channel_access_denied
                  message: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
        "404":
          description: No such check in this channel; product_not_found when the product is not in the channel.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: request_not_found
                  message: No such check in this channel; product_not_found when the product is not in the channel.
        "409":
          description: The check changed since the version you sent; also request_not_ready, request_not_retryable, target_already_exact_match, target_product_not_found and competitor_not_available, with Lobe's message.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: request_changed
                  message: The check changed since the version you sent; also request_not_ready, request_not_retryable, target_already_exact_match, target_product_not_found and competitor_not_available, with Lobe's message.
        "422":
          description: The page's shop is not a competitor of the channel; add it in Pricemind.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: competitor_not_configured
                  message: The page's shop is not a competitor of the channel; add it in Pricemind.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: The match could not be saved; try again. upstream_unavailable when Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: confirmation_failed
                  message: The match could not be saved; try again. upstream_unavailable when Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ManualUrlStart"
            example:
              url: https://shop.example/product/0001
              product_domain_id: "12345"
  /v1/channels/{channel_id}/manual-url-requests/{request_id}:
    get:
      operationId: manual_url_requests.get
      summary: Status of a page check
      tags:
        - Browser companion
      description: The check's current state; each read advances it from the crawl. Requires products:read.
      x-required-scopes:
        - products:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: A channel of the credential's account.
        - name: request_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The check's id from the start response.
      responses:
        "200":
          description: Status of a page check
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManualUrlWorkflow"
              example:
                id: 3f6c1d2e-8a4b-4c5d-9e7f-0a1b2c3d4e5f
                state: ready_for_review
                version: 3
                submitted_url: https://shop.example/product/0001
                preview:
                  product_domain_id: 67890
                  title: Synthetic example kettle
                  url: https://shop.example/product/0001
                  domain: shop.example
                  image: https://shop.example/images/0001.jpg
                  codes:
                    - name: EAN
                      value: "0012345678905"
                  brand: Example Brand
                  price: "99.00"
                  currency: EUR
                  availability: 1
                  observed_at: 2026-10-16T08:00:00Z
                  code_matches:
                    - EAN
                headline: Product ready — your turn
                detail: Check this is the right product, then confirm the match.
                progress: 88
                can_confirm: true
                can_retry: false
                terminal: false
                in_progress: false
                failure: null
        "400":
          description: Unknown or repeated parameter, or an invalid value; details.parameter names it.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Unknown or repeated parameter, or an invalid value; details.parameter names it.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: channel_access_denied
                  message: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
        "404":
          description: No such check in this channel; product_not_found when the product is not in the channel.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: request_not_found
                  message: No such check in this channel; product_not_found when the product is not in the channel.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
  /v1/channels/{channel_id}/manual-url-requests/{request_id}/confirm:
    post:
      operationId: manual_url_requests.confirm
      summary: Confirm the match
      tags:
        - Browser companion
      description: A person confirms the checked page is their product; Pricemind matches it and tracks its prices from then on. Send the version you reviewed. Requires products:read, product_pages:write.
      x-required-scopes:
        - products:read
        - product_pages:write
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: A channel of the credential's account.
        - name: request_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The check's id from the start response.
      responses:
        "200":
          description: Confirm the match
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManualUrlWorkflow"
              example:
                id: 3f6c1d2e-8a4b-4c5d-9e7f-0a1b2c3d4e5f
                state: confirmed
                version: 5
                submitted_url: https://shop.example/product/0001
                preview:
                  product_domain_id: 67890
                  title: Synthetic example kettle
                  url: https://shop.example/product/0001
                  domain: shop.example
                  image: https://shop.example/images/0001.jpg
                  codes:
                    - name: EAN
                      value: "0012345678905"
                  brand: Example Brand
                  price: "99.00"
                  currency: EUR
                  availability: 1
                  observed_at: 2026-10-16T08:00:00Z
                  code_matches:
                    - EAN
                headline: Match confirmed — now tracking
                detail: This competitor's prices will refresh automatically from now on.
                progress: 100
                can_confirm: false
                can_retry: false
                terminal: true
                in_progress: false
                failure: null
        "400":
          description: Unknown or repeated parameter, or an invalid value; details.parameter names it.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Unknown or repeated parameter, or an invalid value; details.parameter names it.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: channel_access_denied
                  message: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
        "404":
          description: No such check in this channel; product_not_found when the product is not in the channel.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: request_not_found
                  message: No such check in this channel; product_not_found when the product is not in the channel.
        "409":
          description: The check changed since the version you sent; also request_not_ready, request_not_retryable, target_already_exact_match, target_product_not_found and competitor_not_available, with Lobe's message.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: request_changed
                  message: The check changed since the version you sent; also request_not_ready, request_not_retryable, target_already_exact_match, target_product_not_found and competitor_not_available, with Lobe's message.
        "422":
          description: The page's shop is not a competitor of the channel; add it in Pricemind.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: competitor_not_configured
                  message: The page's shop is not a competitor of the channel; add it in Pricemind.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: The match could not be saved; try again. upstream_unavailable when Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: confirmation_failed
                  message: The match could not be saved; try again. upstream_unavailable when Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ManualUrlAction"
            example:
              version: 3
  /v1/channels/{channel_id}/manual-url-requests/{request_id}/retry:
    post:
      operationId: manual_url_requests.retry
      summary: Check the page again
      tags:
        - Browser companion
      description: Restarts a failed or timed-out check, or re-reads a page whose fresh price was reused. Send the current version. Requires products:read, product_pages:write.
      x-required-scopes:
        - products:read
        - product_pages:write
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: A channel of the credential's account.
        - name: request_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The check's id from the start response.
      responses:
        "202":
          description: Check the page again
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManualUrlWorkflow"
              example:
                id: 3f6c1d2e-8a4b-4c5d-9e7f-0a1b2c3d4e5f
                state: queued
                version: 5
                submitted_url: https://shop.example/product/0001
                preview: null
                headline: Fresh check queued
                detail: The retailer page is next in line.
                progress: 12
                can_confirm: false
                can_retry: false
                terminal: false
                in_progress: true
                failure: null
        "400":
          description: Unknown or repeated parameter, or an invalid value; details.parameter names it.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Unknown or repeated parameter, or an invalid value; details.parameter names it.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: channel_access_denied
                  message: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
        "404":
          description: No such check in this channel; product_not_found when the product is not in the channel.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: request_not_found
                  message: No such check in this channel; product_not_found when the product is not in the channel.
        "409":
          description: The check changed since the version you sent; also request_not_ready, request_not_retryable, target_already_exact_match, target_product_not_found and competitor_not_available, with Lobe's message.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: request_changed
                  message: The check changed since the version you sent; also request_not_ready, request_not_retryable, target_already_exact_match, target_product_not_found and competitor_not_available, with Lobe's message.
        "422":
          description: The page's shop is not a competitor of the channel; add it in Pricemind.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: competitor_not_configured
                  message: The page's shop is not a competitor of the channel; add it in Pricemind.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: The match could not be saved; try again. upstream_unavailable when Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: confirmation_failed
                  message: The match could not be saved; try again. upstream_unavailable when Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ManualUrlAction"
            example:
              version: 3
  /v1/channels/{channel_id}/manual-url-requests/{request_id}/cancel:
    post:
      operationId: manual_url_requests.cancel
      summary: Not this product
      tags:
        - Browser companion
      description: Retires the check, for example when the person says it is not their product. The crawl already in flight is left alone. Requires products:read, product_pages:write.
      x-required-scopes:
        - products:read
        - product_pages:write
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: A channel of the credential's account.
        - name: request_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The check's id from the start response.
      responses:
        "200":
          description: Not this product
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManualUrlWorkflow"
              example:
                id: 3f6c1d2e-8a4b-4c5d-9e7f-0a1b2c3d4e5f
                state: cancelled
                version: 4
                submitted_url: https://shop.example/product/0001
                preview:
                  product_domain_id: 67890
                  title: Synthetic example kettle
                  url: https://shop.example/product/0001
                  domain: shop.example
                  image: https://shop.example/images/0001.jpg
                  codes:
                    - name: EAN
                      value: "0012345678905"
                  brand: Example Brand
                  price: "99.00"
                  currency: EUR
                  availability: 1
                  observed_at: 2026-10-16T08:00:00Z
                  code_matches:
                    - EAN
                headline: Product check dismissed
                detail: This check was closed and will not be picked up again.
                progress: 100
                can_confirm: false
                can_retry: false
                terminal: true
                in_progress: false
                failure: null
        "400":
          description: Unknown or repeated parameter, or an invalid value; details.parameter names it.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Unknown or repeated parameter, or an invalid value; details.parameter names it.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: channel_access_denied
                  message: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
        "404":
          description: No such check in this channel; product_not_found when the product is not in the channel.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: request_not_found
                  message: No such check in this channel; product_not_found when the product is not in the channel.
        "409":
          description: The check changed since the version you sent; also request_not_ready, request_not_retryable, target_already_exact_match, target_product_not_found and competitor_not_available, with Lobe's message.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: request_changed
                  message: The check changed since the version you sent; also request_not_ready, request_not_retryable, target_already_exact_match, target_product_not_found and competitor_not_available, with Lobe's message.
        "422":
          description: The page's shop is not a competitor of the channel; add it in Pricemind.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: competitor_not_configured
                  message: The page's shop is not a competitor of the channel; add it in Pricemind.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: The match could not be saved; try again. upstream_unavailable when Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: confirmation_failed
                  message: The match could not be saved; try again. upstream_unavailable when Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ManualUrlAction"
            example:
              version: 3
  /v1/channels/{channel_id}/products/{product_domain_id}/history:
    get:
      operationId: channel_product_history.get
      summary: Price history of your product's offers
      tags:
        - Browser companion
      description: "The history window of one of your products: your price, every matched competitor offer, the eMAG buy box with who held it crawl by crawl, your own eMAG offer, a summary over the comparable offers, special-price periods and events, over a range ending today (UTC). Requires products:read, competitor_prices:read."
      x-required-scopes:
        - products:read
        - competitor_prices:read
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: A channel of the credential's account.
        - name: product_domain_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
            description: Decimal identity serialized as a string; never a legacy product_id.
          description: Your channel product.
        - name: range
          in: query
          required: false
          schema:
            type: string
            enum:
              - 1w
              - 2w
              - 1m
              - 2m
              - 3m
              - 6m
              - 12m
            default: 2w
          description: "The window, ending today (UTC) and including it: 1w, 2w, 1m, 2m (every observation) or 3m, 6m, 12m (weekly)."
        - name: basis
          in: query
          required: false
          schema:
            type: string
            enum:
              - incl
              - excl
            default: incl
          description: Prices incl. or excl. VAT.
        - name: If-None-Match
          in: header
          schema:
            type: string
          description: ETag of a previous response; 304 when the representation is unchanged.
      responses:
        "200":
          description: Price history of your product's offers
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
              description: Hash of the complete current representation. Send it as If-None-Match; authentication, scopes and channel access are rechecked before 304.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductHistory"
              example:
                range: 2w
                from: 2026-10-06T00:00:00Z
                to: 2026-10-19T23:59:59Z
                resolution: observation
                currency: EUR
                basis: incl
                series:
                  - key: own
                    role: own
                    offer_id: null
                    domain: own.example
                    seller_name: null
                    color: "#6366f1"
                    set_aside: null
                    ends_at: null
                    points:
                      - t: 2026-10-06T07:12:00Z
                        price: "115.00"
                        regular: "115.00"
                      - t: 2026-10-13T07:10:00Z
                        price: "112.00"
                        regular: "112.00"
                  - key: buybox:67891
                    role: buy_box
                    offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MSIsImVtYWcuYmciLCJtYXJrZXRwbGFjZV9zZWxsZXIiLG51bGwsbnVsbCwiZU1BRyJd
                    domain: emag.bg
                    seller_name: eMAG
                    color: "#9fe029"
                    set_aside: null
                    ends_at: null
                    own_seller_configured: true
                    holders:
                      - from: 2026-10-06T07:55:00Z
                        to: 2026-10-10T09:30:00Z
                        vendor: eMAG
                        is_own: false
                      - from: 2026-10-10T09:30:00Z
                        to: 2026-10-14T07:55:00Z
                        vendor: Example Shop
                        is_own: true
                      - from: 2026-10-14T07:55:00Z
                        to: null
                        vendor: eMAG
                        is_own: false
                    points:
                      - t: 2026-10-06T07:55:00Z
                        price: "112.00"
                        regular: "112.00"
                      - t: 2026-10-10T09:30:00Z
                        price: "109.90"
                        regular: "109.90"
                      - t: 2026-10-14T07:55:00Z
                        price: "106.99"
                        regular: "106.99"
                      - t: 2026-10-19T05:50:00Z
                        price: "106.99"
                        regular: "106.99"
                  - key: own_marketplace:67891
                    role: own_marketplace
                    offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MSIsImVtYWcuYmciLCJtYXJrZXRwbGFjZV9zZWxsZXIiLG51bGwsbnVsbCwiRXhhbXBsZSBTaG9wIl0
                    domain: emag.bg
                    seller_name: Example Shop
                    color: "#6366f1"
                    set_aside: null
                    ends_at: null
                    points:
                      - t: 2026-10-06T07:55:00Z
                        price: "111.50"
                        regular: "111.50"
                      - t: 2026-10-10T09:30:00Z
                        price: "109.90"
                        regular: "109.90"
                      - t: 2026-10-14T07:55:00Z
                        price: "109.90"
                        regular: "109.90"
                      - t: 2026-10-19T05:50:00Z
                        price: "109.90"
                        regular: "109.90"
                  - key: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                    role: competitor
                    offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                    domain: shop.example
                    seller_name: null
                    color: "#e029cd"
                    set_aside: null
                    ends_at: null
                    points:
                      - t: 2026-10-06T06:10:00Z
                        price: "108.00"
                        regular: "120.00"
                      - t: 2026-10-13T06:05:00Z
                        price: "108.00"
                        regular: "120.00"
                summary:
                  comparable_count: 4
                  average_now: "107.70"
                  lowest:
                    offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MSIsImVtYWcuYmciLCJtYXJrZXRwbGFjZV9zZWxsZXIiLG51bGwsbnVsbCwiTWFya2V0IFNlbGxlciJd
                    price: "105.90"
                    since: 2026-10-14T07:55:00Z
                  highest:
                    offer_id: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MSIsImVtYWcuYmciLCJtYXJrZXRwbGFjZV9zZWxsZXIiLG51bGwsbnVsbCwiZU1BRyJd
                    price: "112.00"
                    since: 2026-10-06T07:55:00Z
                special_prices:
                  - key: v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0
                    discount_percent: "10.0"
                    from: 2026-10-01T08:00:00Z
                    to: null
                events:
                  - at: 2026-10-14T07:55:00Z
                    key: buybox:67891
                    type: buy_box_change
                    from: "109.90"
                    to: "106.99"
                    promo: null
                    from_vendor: Example Shop
                    to_vendor: eMAG
                    from_is_own: true
                    to_is_own: false
                    own_price: "109.90"
                  - at: 2026-10-14T07:55:00Z
                    key: buybox:67891
                    type: price_drop
                    from: "109.90"
                    to: "106.99"
                    promo: null
                  - at: 2026-10-13T07:10:00Z
                    key: own
                    type: price_drop
                    from: "115.00"
                    to: "112.00"
                    promo: null
                  - at: 2026-10-10T09:30:00Z
                    key: buybox:67891
                    type: buy_box_change
                    from: "112.00"
                    to: "109.90"
                    promo: null
                    from_vendor: eMAG
                    to_vendor: Example Shop
                    from_is_own: false
                    to_is_own: true
                    own_price: "109.90"
                  - at: 2026-10-10T09:30:00Z
                    key: buybox:67891
                    type: price_drop
                    from: "112.00"
                    to: "109.90"
                    promo: null
                  - at: 2026-10-10T09:30:00Z
                    key: own_marketplace:67891
                    type: price_drop
                    from: "111.50"
                    to: "109.90"
                    promo: null
                events_truncated: false
        "304":
          description: Unchanged since the supplied ETag; no body.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Cache-Control:
              schema:
                type: string
              description: private, no-cache. Customer data must never be cached publicly.
            ETag:
              schema:
                type: string
        "400":
          description: Unknown or repeated parameter, or an invalid value; details.parameter names it.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: invalid_input
                  message: Unknown or repeated parameter, or an invalid value; details.parameter names it.
        "401":
          description: The credential is missing, invalid, revoked or expired; sign in again.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: unauthorized
                  message: The credential is missing, invalid, revoked or expired; sign in again.
        "403":
          description: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: channel_access_denied
                  message: The channel is not in the credential's account; insufficient_scope when a scope is missing; subject_inactive when the person was removed or deactivated.
        "404":
          description: The product is not in this channel.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: product_not_found
                  message: The product is not in this channel.
        "429":
          description: The credential's hourly limit is reached; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: rate_limited
                  message: The credential's hourly limit is reached; see Retry-After.
        "502":
          description: Pricemind could not complete the request.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: Pricemind could not complete the request.
        "503":
          description: The service or a complete representation is temporarily unavailable; see Retry-After.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
            Retry-After:
              schema:
                type: string
              description: Seconds until a meaningful retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_unavailable
                  message: The service or a complete representation is temporarily unavailable; see Retry-After.
        "504":
          description: The request timed out.
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request correlation ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogReadError"
              example:
                error:
                  code: upstream_timeout
                  message: The request timed out.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |-
        Pricemind API key. Send it in the `X-API-Key` header. The `Authorization: Bearer <key>` form is also accepted.

        Canonical format: `pmk_<version>_<key-id>.<secret>`.
      example: pmk_v1_00000000-0000-4000-8000-000000000000.example-secret
  parameters:
    ChannelId:
      name: channelId
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
    ChannelSourceId:
      name: channelSourceId
      in: path
      required: true
      description: Persisted channel source ID.
      schema:
        type: integer
        format: int32
        minimum: 1
    SourceRunId:
      name: sourceRunId
      in: path
      required: true
      description: Durable source dispatch-ledger run ID.
      schema:
        type: integer
        format: int64
        minimum: 1
    CrawlRequestId:
      name: requestId
      in: path
      required: true
      schema:
        type: string
        format: uuid
  responses:
    CrawlError:
      description: Crawl request error; status and stable error details are preserved from the owner service.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CrawlError"
    SourcePublicError:
      description: Stable public source-operation error; internal and provider details are not exposed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SourcePublicError"
  schemas:
    ChannelSourceListEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
        - count
        - next_cursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ChannelSource"
        count:
          type: integer
          minimum: 0
          description: Number of sources in this response.
        next_cursor:
          type: string
          nullable: true
          description: Reserved pagination cursor; currently null for source lists.
    ChannelSourceEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/ChannelSource"
    ChannelSource:
      type: object
      additionalProperties: false
      description: |
        Safe public channel-source state. The underlying `config` field is
        intentionally omitted because it can contain credentials, bearer
        tokens, signed URLs, or other provider secrets. `selected` reports
        channel selection; it does not imply that synchronization is enabled.
      required:
        - channel_source_id
        - channel_id
        - spider_job_id
        - title
        - type
        - items
        - persisted
        - selected
        - sync
        - latest_run
        - created_at
        - updated_at
      properties:
        channel_source_id:
          type: integer
          format: int32
          minimum: 1
        channel_id:
          type: integer
          format: int32
          minimum: 1
        spider_job_id:
          type: integer
          format: int32
          minimum: 1
          nullable: true
          description: Spider job link when this source uses a crawler job.
        title:
          type: string
        type:
          type: string
        items:
          type: integer
          format: int32
          minimum: 0
        persisted:
          type: boolean
        selected:
          type: boolean
          description: Whether this source is selected by the channel.
        sync:
          $ref: "#/components/schemas/ChannelSourceSync"
        latest_run:
          allOf:
            - $ref: "#/components/schemas/SourceRun"
          nullable: true
          description: Most recent durable dispatch run, or null when none exists.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
    ChannelSourceSync:
      type: object
      additionalProperties: false
      description: |
        Source synchronization eligibility and scheduling state. `enabled` is
        the inverse convenience view of the persisted `disabled` flag. This flag
        controls scheduled synchronization only; explicitly authorized manual
        API runs remain available. Scheduled runs additionally require a schedule
        and due `next_run`.
      required:
        - enabled
        - disabled
        - schedule
        - timezone
        - next_run
        - last_run
      properties:
        enabled:
          type: boolean
        disabled:
          type: boolean
        schedule:
          type: string
          nullable: true
          description: Source schedule expression, or null when unscheduled.
        timezone:
          type: string
          nullable: true
          description: IANA timezone used to evaluate the source schedule.
        next_run:
          type: string
          format: date-time
          nullable: true
          description: Next scheduled occurrence in UTC, when applicable.
        last_run:
          type: string
          format: date-time
          nullable: true
          description: Last source-run time in UTC, when available.
    SourceRunStartRequest:
      type: object
      additionalProperties: false
      properties:
        test:
          type: boolean
          default: false
          description: Request the source owner's test-run behavior.
    SourceRunListEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
        - count
        - next_cursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SourceRun"
        count:
          type: integer
          minimum: 0
          description: Number of runs in this page.
        next_cursor:
          type: string
          nullable: true
          description: Opaque cursor for the next page, or null at the end.
    SourceRunEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/SourceRun"
    SourceRun:
      type: object
      additionalProperties: false
      description: |
        One durable source-dispatch occurrence. `source_run_id` is the numeric
        dispatch-ledger identity and remains stable if the dispatch is retried
        with different downstream spider, crawl, or import links.
      required:
        - source_run_id
        - channel_source_id
        - channel_id
        - trigger
        - status
        - attempt
        - test
        - spider_run_id
        - crawl_id
        - import_run_id
        - pipeline_status
        - progress
        - scheduled_for
        - next_attempt_at
        - dispatch_started_at
        - loading_started_at
        - failed_at
        - finished_at
        - created_at
        - updated_at
        - failure
      properties:
        source_run_id:
          type: integer
          format: int64
          minimum: 1
          description: Durable source-dispatch ledger ID.
        channel_source_id:
          type: integer
          format: int32
          minimum: 1
        channel_id:
          type: integer
          format: int32
          minimum: 1
        trigger:
          type: string
          enum:
            - manual
            - scheduled
        status:
          type: string
          enum:
            - pending
            - dispatching
            - waiting_for_loading
            - retry_scheduled
            - loading_started
            - succeeded
            - failed
            - abandoned
        attempt:
          type: integer
          format: int32
          minimum: 0
        test:
          type: boolean
          nullable: true
          description: Test mode when known from the dispatched spider run.
        spider_run_id:
          type: integer
          format: int32
          minimum: 1
          nullable: true
        crawl_id:
          type: string
          format: uuid
          nullable: true
        import_run_id:
          type: integer
          format: int64
          minimum: 1
          nullable: true
        pipeline_status:
          type: string
          nullable: true
          description: Downstream import pipeline status when an import exists.
        progress:
          $ref: "#/components/schemas/SourceRunProgress"
        scheduled_for:
          type: string
          format: date-time
          description: UTC occurrence represented by this run.
        next_attempt_at:
          type: string
          format: date-time
          nullable: true
        dispatch_started_at:
          type: string
          format: date-time
          nullable: true
        loading_started_at:
          type: string
          format: date-time
          nullable: true
        failed_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
        failure:
          allOf:
            - $ref: "#/components/schemas/SourceRunFailure"
          nullable: true
          description: Stable sanitized failure, or null when no failure is exposed.
    SourceRunProgress:
      type: object
      additionalProperties: false
      description: |
        Import counters. All values are zero until a downstream import run is
        linked; zero is meaningful and is not the same as unavailable.
      required:
        - source_total_items
        - extraction_failed_items
        - total_items
        - processed_items
        - failed_items
        - percent
      properties:
        source_total_items:
          type: integer
          format: int32
          minimum: 0
        extraction_failed_items:
          type: integer
          format: int32
          minimum: 0
        total_items:
          type: integer
          format: int32
          minimum: 0
        processed_items:
          type: integer
          format: int32
          minimum: 0
        failed_items:
          type: integer
          format: int32
          minimum: 0
        percent:
          type: number
          format: double
          minimum: 0
          maximum: 100
    SourceRunFailure:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable public failure code.
        message:
          type: string
          description: Sanitized failure message without provider or config secrets.
    SourcePublicError:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    CrawlStartRequest:
      type: object
      additionalProperties: false
      required:
        - policy
        - reason
        - idempotency_key
      oneOf:
        - required:
            - url
        - required:
            - targets
        - required:
            - segment
      properties:
        url:
          type: string
          format: uri
          maxLength: 8192
          description: One HTTP(S) URL; cannot contain user credentials.
        targets:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: "#/components/schemas/CrawlTargetInput"
        segment:
          $ref: "#/components/schemas/CrawlSegmentSelector"
        policy:
          type: string
          enum:
            - force
            - stale_only
        reason:
          type: string
          minLength: 1
          maxLength: 500
        idempotency_key:
          type: string
          minLength: 8
          maxLength: 128
          pattern: ^[A-Za-z0-9._~:-]+$
    CrawlTargetInput:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          maxLength: 8192
        product_domain_id:
          type: integer
          format: int64
          minimum: 1
    CrawlSegmentSelector:
      type: object
      additionalProperties: false
      required:
        - segment_id
        - target_set
      properties:
        segment_id:
          type: integer
          format: int64
          minimum: 1
        target_set:
          type: string
          enum:
            - own
            - regular_market
            - group_market
            - all_market
    CrawlRequestEnvelope:
      type: object
      required:
        - status
        - request
      properties:
        status:
          type: boolean
          enum:
            - true
        replayed:
          type: boolean
        request:
          $ref: "#/components/schemas/CrawlRequest"
        targets:
          type: array
          items:
            $ref: "#/components/schemas/CrawlTarget"
    CrawlRequest:
      type: object
      required:
        - request_id
        - channel_run_id
        - spider_run_id
        - channel_id
        - state
        - pipeline_status
        - policy
        - reason
        - target_count
        - leaf_target_count
        - counts
        - created_at
        - updated_at
      properties:
        request_id:
          type: string
          format: uuid
        channel_run_id:
          type: integer
          format: int64
        spider_run_id:
          type: integer
          format: int64
        channel_id:
          type: integer
          format: int32
        state:
          type: string
        pipeline_status:
          type: string
        policy:
          type: string
          enum:
            - force
            - stale_only
        reason:
          type: string
        target_count:
          type: integer
          minimum: 0
        leaf_target_count:
          type: integer
          minimum: 0
        counts:
          type: object
          additionalProperties:
            type: integer
        error:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          nullable: true
    CrawlTargetsEnvelope:
      type: object
      required:
        - status
        - request_id
        - targets
      properties:
        status:
          type: boolean
          enum:
            - true
        request_id:
          type: string
          format: uuid
        targets:
          type: array
          items:
            $ref: "#/components/schemas/CrawlTarget"
        next_cursor:
          type: string
    CrawlTarget:
      type: object
      required:
        - target_id
        - url
        - state
        - pipeline_state
        - attempts
      properties:
        target_id:
          type: string
          format: uuid
        parent_target_id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        product_domain_id:
          type: integer
          format: int64
        state:
          type: string
        pipeline_state:
          type: string
        attempts:
          type: integer
          minimum: 0
        status_code:
          type: integer
        final_url:
          type: string
          format: uri
        transformed_ids:
          type: array
          items:
            type: integer
            format: int64
        product_price_id:
          type: integer
          format: int64
        error:
          type: string
        queued_at:
          type: string
          format: date-time
        request_started_at:
          type: string
          format: date-time
        dispatched_at:
          type: string
          format: date-time
        crawled_at:
          type: string
          format: date-time
        transformed_at:
          type: string
          format: date-time
        loaded_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CrawlError:
      type: object
      required:
        - error
      properties:
        status:
          type: boolean
          enum:
            - false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        message:
          type: string
    Channel:
      type: object
      description: Channel information
      properties:
        id:
          type: string
          description: Unique channel identifier
          example: amzn
        name:
          type: string
          description: Human-readable channel name
          example: Amazon
        type:
          type: string
          description: Type of channel
          enum:
            - marketplace
            - ads
            - other
          example: marketplace
      required:
        - id
        - name
        - type
    ChannelDetailed:
      type: object
      description: Detailed channel information from database
      properties:
        channel_id:
          type: integer
          description: Unique channel identifier
          example: 123
        name:
          type: string
          description: Human-readable channel name
          example: Amazon Store
        channel:
          type: string
          description: Channel type/category
          example: ecommerce
        currency:
          type: string
          description: Currency code for the channel
          example: USD
        vat:
          type: number
          format: double
          description: VAT rate for the channel
          example: 0.2
        status:
          type: integer
          description: Channel status (0=inactive, 1=active)
          example: 1
      required:
        - channel_id
        - name
        - channel
        - currency
        - vat
        - status
    CreatePriceRequest:
      type: object
      description: Request payload for creating a new product price
      properties:
        product_sku:
          type: string
          description: Product SKU (Stock Keeping Unit) - unique product identifier
          minLength: 1
          maxLength: 255
          example: PROD-12345
        price:
          type: string
          description: |
            Base price as a decimal string.
            Must be a valid decimal number greater than 0.
          pattern: ^\d+(\.\d+)?$
          example: "29.99"
        special_price:
          type: string
          nullable: true
          description: |
            Special/discounted price as a decimal string.
            Must be less than the base price.
          pattern: ^\d+(\.\d+)?$
          example: "24.99"
        delivery_price:
          type: string
          nullable: true
          description: |
            Delivery/shipping cost as a decimal string.
          pattern: ^\d+(\.\d+)?$
          example: "5.99"
        currency:
          type: string
          nullable: true
          description: |
            Currency code (ISO 4217).
            If not provided, uses the channel's default currency.
          minLength: 3
          maxLength: 3
          example: USD
        includes_tax:
          type: boolean
          description: |
            Whether the provided prices include tax.
            If true, tax will be calculated and removed from the stored price.
            If false, tax will be calculated and added to create tax-inclusive prices.
          default: false
          example: false
        tax_rate:
          type: string
          nullable: true
          description: |
            Tax rate as a decimal string (e.g., 0.20 for 20%).
            If not provided, uses the channel's default VAT rate.
          pattern: ^\d+(\.\d+)?$
          example: "0.20"
        origin:
          type: string
          nullable: true
          description: |
            Origin of the price data.
            Used for tracking the source of price information.
          default: api
          example: manual
      required:
        - product_sku
        - price
    CreatePriceResponse:
      type: object
      description: Response after successfully creating a price
      properties:
        product_price_id:
          type: integer
          format: int64
          description: Unique identifier for the created price record
          example: 12345
        status:
          type: string
          description: Status of the price creation
          enum:
            - created
            - pending
            - failed
          example: created
    Error:
      type: object
      description: Standard error response
      properties:
        error:
          type: string
          description: Human-readable error message
          example: Invalid request body
      required:
        - error
    CatalogDescription:
      type: object
      additionalProperties: false
      required:
        - format
        - content
      properties:
        format:
          type: string
          nullable: true
          enum:
            - text
            - html
            - null
        content:
          type: string
      description: Collected content is preserved. Format is text/html only when explicit source metadata is known; otherwise null. Sanitize HTML and render unknown-format content safely.
    CatalogBrand:
      type: object
      additionalProperties: false
      required:
        - id
        - name
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
    CatalogCategory:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - path
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        path:
          type: array
          items:
            type: string
          nullable: true
    CatalogImage:
      type: object
      additionalProperties: false
      required:
        - url
        - alt
        - width
        - height
      properties:
        url:
          type: string
        alt:
          type: string
          nullable: true
        width:
          type: integer
          nullable: true
          minimum: 1
        height:
          type: integer
          nullable: true
          minimum: 1
    CatalogAttribute:
      type: object
      additionalProperties: false
      required:
        - name
        - label
        - data_type
        - value
        - unit
      properties:
        name:
          type: string
        label:
          type: string
          nullable: true
        data_type:
          type: string
          enum:
            - boolean
            - integer
            - decimal
            - string
            - array
            - object
        value:
          description: JSON value matches data_type; decimal values are strings. Null is unknown.
        unit:
          type: string
          nullable: true
      oneOf:
        - properties:
            data_type:
              type: string
              enum:
                - boolean
            value:
              type: boolean
              nullable: true
        - properties:
            data_type:
              type: string
              enum:
                - integer
            value:
              type: integer
              nullable: true
        - properties:
            data_type:
              type: string
              enum:
                - decimal
            value:
              type: string
              nullable: true
              pattern: ^-?[0-9]+(?:\.[0-9]+)?$
        - properties:
            data_type:
              type: string
              enum:
                - string
            value:
              type: string
              nullable: true
        - properties:
            data_type:
              type: string
              enum:
                - array
            value:
              type: array
              nullable: true
              items: {}
        - properties:
            data_type:
              type: string
              enum:
                - object
            value:
              type: object
              nullable: true
    CatalogCustomField:
      type: object
      additionalProperties: false
      required:
        - machine_name
        - label
        - data_type
        - value
      properties:
        machine_name:
          type: string
        label:
          type: string
          nullable: true
        data_type:
          type: string
          enum:
            - boolean
            - integer
            - decimal
            - string
            - array
            - object
        value:
          description: JSON value matches data_type; decimal values are strings. Null is unknown.
      oneOf:
        - properties:
            data_type:
              type: string
              enum:
                - boolean
            value:
              type: boolean
              nullable: true
        - properties:
            data_type:
              type: string
              enum:
                - integer
            value:
              type: integer
              nullable: true
        - properties:
            data_type:
              type: string
              enum:
                - decimal
            value:
              type: string
              nullable: true
              pattern: ^-?[0-9]+(?:\.[0-9]+)?$
        - properties:
            data_type:
              type: string
              enum:
                - string
            value:
              type: string
              nullable: true
        - properties:
            data_type:
              type: string
              enum:
                - array
            value:
              type: array
              nullable: true
              items: {}
        - properties:
            data_type:
              type: string
              enum:
                - object
            value:
              type: object
              nullable: true
    CatalogVariant:
      type: object
      additionalProperties: false
      required:
        - is_configurable
        - parent_product_domain_id
        - attributes
      properties:
        is_configurable:
          type: boolean
          nullable: true
        parent_product_domain_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: Decimal identity serialized as a string; never a legacy product_id.
          nullable: true
        attributes:
          type: array
          items:
            $ref: "#/components/schemas/CatalogAttribute"
    CatalogProduct:
      type: object
      additionalProperties: false
      required:
        - product_domain_id
        - sku
        - title
        - url
        - locale
        - description
        - brand
        - codes
        - categories
        - images
        - attributes
        - variant
        - custom_fields
        - updated_at
        - field_status
      properties:
        product_domain_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: Decimal identity serialized as a string; never a legacy product_id.
        sku:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
        locale:
          type: string
          nullable: true
        description:
          type: object
          additionalProperties: false
          required:
            - format
            - content
          properties:
            format:
              type: string
              nullable: true
              enum:
                - text
                - html
                - null
            content:
              type: string
          description: Collected content is preserved. Format is text/html only when explicit source metadata is known; otherwise null. Sanitize HTML and render unknown-format content safely.
          nullable: true
        brand:
          type: object
          additionalProperties: false
          required:
            - id
            - name
          properties:
            id:
              type: string
              nullable: true
            name:
              type: string
              nullable: true
          nullable: true
        codes:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Collected identifier keys, including canonical ean; preserve leading zeroes and distinct values.
        categories:
          type: array
          items:
            $ref: "#/components/schemas/CatalogCategory"
        images:
          type: array
          items:
            $ref: "#/components/schemas/CatalogImage"
        attributes:
          type: array
          items:
            $ref: "#/components/schemas/CatalogAttribute"
        variant:
          type: object
          additionalProperties: false
          required:
            - is_configurable
            - parent_product_domain_id
            - attributes
          properties:
            is_configurable:
              type: boolean
              nullable: true
            parent_product_domain_id:
              type: string
              pattern: ^[1-9][0-9]*$
              description: Decimal identity serialized as a string; never a legacy product_id.
              nullable: true
            attributes:
              type: array
              items:
                $ref: "#/components/schemas/CatalogAttribute"
          nullable: true
        custom_fields:
          type: array
          items:
            $ref: "#/components/schemas/CatalogCustomField"
        updated_at:
          type: string
          nullable: true
          format: date-time
          pattern: Z$
          description: Existing catalog/source update time when available; not a complete-response indexing timestamp.
        field_status:
          type: object
          additionalProperties:
            type: string
            enum:
              - unknown
              - not_collected
              - unsupported
          description: Known-empty groups use empty arrays and no missing status. Entitlement-hidden field names are never listed.
      description: Complete available catalog from the existing product identity and selected source, enriched with related collected data. Required keys remain present with explicit null/empty unknowns. Catalog reads do not replace indexed channel prices or offer selection.
    PriceAmounts:
      type: object
      additionalProperties: false
      required:
        - excl_tax
        - incl_tax
      properties:
        excl_tax:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
        incl_tax:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
    CurrentPrice:
      type: object
      additionalProperties: false
      required:
        - currency
        - regular
        - special
        - effective
        - delivery
        - tax_rate
        - effective_includes_delivery
        - product_price_id
        - observed_at
        - stale_at
      properties:
        currency:
          type: string
          nullable: true
          pattern: ^[A-Z]{3}$
        regular:
          $ref: "#/components/schemas/PriceAmounts"
        special:
          $ref: "#/components/schemas/PriceAmounts"
        effective:
          $ref: "#/components/schemas/PriceAmounts"
        delivery:
          $ref: "#/components/schemas/PriceAmounts"
        tax_rate:
          type: string
          nullable: true
          pattern: ^-?[0-9]+(?:\.[0-9]+)?$
          description: Exact decimal string. Null is unknown; zero is a known zero.
        effective_includes_delivery:
          type: boolean
        product_price_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: Decimal identity serialized as a string; never a legacy product_id.
          nullable: true
        observed_at:
          type: string
          nullable: true
          format: date-time
          pattern: Z$
          description: RFC3339 UTC.
        stale_at:
          type: string
          nullable: true
          format: date-time
          pattern: Z$
          description: RFC3339 UTC.
      description: Existing stored amount/currency/tax semantics. Primary and split prices and own named prices use indexed channel rows. Competitor named prices retain the declared currency of their existing collected price row, which can differ from channel currency; no read-time FX conversion is implied. Delivery inclusion is explicit; no inferred landed total or FX provenance. Failures retain observed money instead of zero placeholders.
    AdditionalPrice:
      type: object
      additionalProperties: false
      required:
        - field_id
        - name
        - price
      properties:
        field_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: Decimal identity serialized as a string; never a legacy product_id.
        name:
          type: string
        price:
          $ref: "#/components/schemas/CurrentPrice"
      description: Existing named-price definition and stored amounts. Own entries come from indexed channel_product_prices; competitor entries come from existing collected product_prices and retain that row currency. Always read price.currency; do not assume every named competitor price is normalized to the primary channel price currency.
    CatalogQuality:
      type: object
      additionalProperties: false
      required:
        - is_stale
        - eligible_for_comparison
        - reasons
      properties:
        is_stale:
          type: boolean
          nullable: true
        eligible_for_comparison:
          type: boolean
          nullable: true
        reasons:
          type: array
          items:
            type: string
            enum:
              - stale
              - scrape_failed
              - not_found
              - unavailable
              - missing_price
              - unknown
      description: Eligibility follows Lobe selection; a reason does not automatically imply ineligible.
    OfferRelationship:
      type: object
      additionalProperties: false
      required:
        - kind
        - match_source
        - selected_for_comparison
        - seller_id
        - seller_name
        - split_criteria
      properties:
        kind:
          type: string
          enum:
            - primary
            - split
            - marketplace_seller
        match_source:
          type: string
          nullable: true
          enum:
            - system
            - user
            - both
            - null
        selected_for_comparison:
          type: boolean
        seller_id:
          type: string
          nullable: true
        seller_name:
          type: string
          nullable: true
          description: Marketplace seller (vendor) name for marketplace_seller offers; null for primary and split offers.
        split_criteria:
          type: string
          nullable: true
      description: Current selected association structure, not exact versus substitute confidence.
    CatalogAvailability:
      type: integer
      nullable: true
      description: "Known domain defaults: 0 out_of_stock, 1 in_stock, 2 unknown. Other configured/provider integer codes are retained with provider-specific meanings. Null is unknown; 2 does not mean on demand."
      x-known-values:
        "0": out_of_stock
        "1": in_stock
        "2": unknown
    CatalogStatus:
      type: integer
      nullable: true
      description: "Known domain defaults: 0 disabled, 1 enabled. Other configured/provider integer codes are retained with provider-specific meanings. Null is unknown. This is product state, never a scrape-failure enum."
      x-known-values:
        "0": disabled
        "1": enabled
    Offer:
      type: object
      additionalProperties: false
      required:
        - offer_id
        - channel_id
        - main_product_domain_id
        - competitor
        - product
        - url
        - relationship
        - price
        - additional_prices
        - availability
        - status
        - quality
        - links
      properties:
        offer_id:
          type: string
          pattern: ^v1\.[A-Za-z0-9_-]+$
          description: Versioned opaque logical association ID. Stable across replacement price rows; not an authorization token.
        channel_id:
          type: integer
          minimum: 1
        main_product_domain_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: Decimal identity serialized as a string; never a legacy product_id.
        competitor:
          type: object
          additionalProperties: false
          required:
            - domain
          properties:
            domain:
              type: string
        product:
          $ref: "#/components/schemas/CatalogProduct"
        url:
          type: string
          nullable: true
        relationship:
          $ref: "#/components/schemas/OfferRelationship"
        price:
          $ref: "#/components/schemas/CurrentPrice"
        additional_prices:
          type: array
          items:
            $ref: "#/components/schemas/AdditionalPrice"
        availability:
          $ref: "#/components/schemas/CatalogAvailability"
        status:
          $ref: "#/components/schemas/CatalogStatus"
        quality:
          $ref: "#/components/schemas/CatalogQuality"
        links:
          type: object
          additionalProperties: false
          required:
            - self
          properties:
            self:
              type: string
    Product:
      type: object
      additionalProperties: false
      required:
        - channel_id
        - catalog
        - price
        - additional_prices
        - availability
        - status
        - quality
        - links
      properties:
        channel_id:
          type: integer
          minimum: 1
        catalog:
          $ref: "#/components/schemas/CatalogProduct"
        price:
          $ref: "#/components/schemas/CurrentPrice"
        additional_prices:
          type: array
          items:
            $ref: "#/components/schemas/AdditionalPrice"
        availability:
          $ref: "#/components/schemas/CatalogAvailability"
        status:
          $ref: "#/components/schemas/CatalogStatus"
        quality:
          $ref: "#/components/schemas/CatalogQuality"
        links:
          type: object
          additionalProperties: false
          required:
            - self
            - offers
          properties:
            self:
              type: string
            offers:
              type: string
        offers:
          $ref: "#/components/schemas/OfferPage"
      description: Same normalized schema for list, detail and exact SKU lookup. offers is omitted unless include=offers; links.offers always remains.
    ProductPage:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
        - links
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Product"
        pagination:
          type: object
          additionalProperties: false
          required:
            - limit
            - has_more
            - next_cursor
          properties:
            limit:
              type: integer
              minimum: 1
              maximum: 500
            has_more:
              type: boolean
            next_cursor:
              type: string
              nullable: true
        links:
          type: object
          additionalProperties: false
          required:
            - next
          properties:
            next:
              type: string
              nullable: true
        meta:
          type: object
          additionalProperties: false
          required:
            - consistency
            - coverage
          properties:
            consistency:
              type: string
              enum:
                - live
            coverage:
              type: string
              enum:
                - channel_products
      description: Deterministic keyset live page. No total/count or immutable multi-page snapshot guarantee. Cursors expire after 24 hours and bind endpoint, authorized visibility, selected source identity, filters/includes, ordering and last key; page limit may change. A current source mismatch returns source_changed; an intervening A-to-B-to-A transition is not guaranteed to invalidate a cursor.
    OfferPage:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
        - links
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Offer"
        pagination:
          type: object
          additionalProperties: false
          required:
            - limit
            - has_more
            - next_cursor
          properties:
            limit:
              type: integer
              minimum: 1
              maximum: 500
            has_more:
              type: boolean
            next_cursor:
              type: string
              nullable: true
        links:
          type: object
          additionalProperties: false
          required:
            - next
          properties:
            next:
              type: string
              nullable: true
        meta:
          type: object
          additionalProperties: false
          required:
            - consistency
            - coverage
          properties:
            consistency:
              type: string
              enum:
                - live
            coverage:
              type: string
              enum:
                - selected_matched_offers
      description: Deterministic keyset live page. No total/count or immutable multi-page snapshot guarantee. Cursors expire after 24 hours and bind endpoint, authorized visibility, selected source identity, filters/includes, ordering and last key; page limit may change. A current source mismatch returns source_changed; an intervening A-to-B-to-A transition is not guaranteed to invalidate a cursor.
    ProductEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/Product"
    OfferEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/Offer"
    CatalogReadError:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
    ExtensionTrackedCompetitor:
      type: object
      additionalProperties: false
      required:
        - channel_competitor_id
        - domain
        - status
      properties:
        channel_competitor_id:
          type: integer
          minimum: 1
        domain:
          type: string
        status:
          type: string
          enum:
            - active
            - inactive
            - issues
      description: A configured competitor shop of the channel, read live (not from the channel_domains materialized view). status is the channel competitor's state in Lobe; it does not decide whether the shop is crawled.
    ExtensionTrackedChannel:
      type: object
      additionalProperties: false
      required:
        - channel_id
        - name
        - currency
        - own_domains
        - competitors
      properties:
        channel_id:
          type: integer
          minimum: 1
        name:
          type: string
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        own_domains:
          type: array
          items:
            type: string
        competitors:
          type: array
          items:
            $ref: "#/components/schemas/ExtensionTrackedCompetitor"
      description: One channel the credential can read. own_domains is the channel shop domain (empty when none is configured).
    ExtensionTrackedDomains:
      type: array
      items:
        $ref: "#/components/schemas/ExtensionTrackedChannel"
      description: Every channel of the credential's account that the credential may read, ordered by channel_id. The extension looks up only pages on these domains.
    ExtensionResolveMatch:
      type: object
      additionalProperties: false
      required:
        - channel_id
        - main_product
        - competitor_product_domain_id
        - channel_competitor_id
        - match_source
      properties:
        channel_id:
          type: integer
          minimum: 1
        main_product:
          $ref: "#/components/schemas/Product"
        competitor_product_domain_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: The viewed page's product_domain_id when it is a competitor page of main_product (its offer has product.product_domain_id equal to this); null when the page is the channel's own product.
          nullable: true
        channel_competitor_id:
          type: integer
          minimum: 1
          nullable: true
          description: The channel competitor the viewed page belongs to; null for own pages.
        match_source:
          type: string
          nullable: true
          enum:
            - system
            - user
            - both
            - null
          description: How the page was matched to main_product; user or both means matched by hand. Null for own pages.
        rule:
          $ref: "#/components/schemas/RuleSuggestion"
      description: One (channel, product) pair the viewed page belongs to. main_product is the PRI-1009 Product; with include=offers its offers page holds the channel's matched offers (first 20, continue with links.next). rule is present with include=rule.
    ExtensionPageSnapshot:
      type: object
      additionalProperties: false
      required:
        - catalog
        - price
        - availability
      properties:
        catalog:
          $ref: "#/components/schemas/CatalogProduct"
        price:
          $ref: "#/components/schemas/CurrentPrice"
        availability:
          $ref: "#/components/schemas/CatalogAvailability"
      description: "What Pricemind collected for a known page no product of the account uses yet: its catalog and latest base price (no source, no named price field), in the page's own currency."
    ExtensionResolve:
      type: object
      additionalProperties: false
      required:
        - domain
        - viewed_as
        - matches
        - trackable_channels
        - page
      properties:
        domain:
          type: string
          description: The page host without a leading www.
        viewed_as:
          type: string
          enum:
            - own
            - competitor
            - unmatched
            - not_tracked
          description: "own: the page is one of your channel products; competitor: a matched competitor page; unmatched: a known page of a tracked shop that none of your products uses; not_tracked: an unknown page, or a shop none of your channels tracks."
        matches:
          type: array
          items:
            $ref: "#/components/schemas/ExtensionResolveMatch"
        trackable_channels:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - channel_id
              - channel_competitor_id
            properties:
              channel_id:
                type: integer
                minimum: 1
              channel_competitor_id:
                type: integer
                minimum: 1
        page:
          type: object
          additionalProperties: false
          required:
            - catalog
            - price
            - availability
          properties:
            catalog:
              $ref: "#/components/schemas/CatalogProduct"
            price:
              $ref: "#/components/schemas/CurrentPrice"
            availability:
              $ref: "#/components/schemas/CatalogAvailability"
          description: "What Pricemind collected for a known page no product of the account uses yet: its catalog and latest base price (no source, no named price field), in the page's own currency."
          nullable: true
      description: Every channel and product of the account the page belongs to. Two or more matches in different channels drive the channel selector; two in one channel drive the product picker. trackable_channels lists channels where the page's shop is a competitor and the page is not matched yet, so it can be added to a product. page is set only for unmatched.
    OfferHistoryPoint:
      type: object
      additionalProperties: false
      required:
        - date
        - price
      properties:
        date:
          type: string
          format: date-time
          pattern: Z$
          description: Observation time, RFC3339 UTC.
        price:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
    OfferHistory:
      type: object
      additionalProperties: false
      required:
        - period_days
        - currency
        - points
      properties:
        period_days:
          type: integer
          minimum: 1
          maximum: 30
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        points:
          type: array
          items:
            $ref: "#/components/schemas/OfferHistoryPoint"
      description: Eligible observed prices of one matched offer (special price when set, else regular, incl. VAT) converted to the channel currency, oldest first. The same series as the Lobe price grid's 30-day preview.
    RuleSuggestionRule:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - execution_mode
        - next_execution_at
      properties:
        id:
          type: integer
          minimum: 1
        name:
          type: string
        execution_mode:
          type: string
          enum:
            - scheduled
            - auto
            - manual
          description: scheduled runs at next_execution_at, auto after each index refresh, manual when someone starts it.
        next_execution_at:
          type: string
          nullable: true
          format: date-time
          pattern: Z$
          description: Next planned run of a scheduled rule, RFC3339 UTC; null for auto and manual rules. Scheduled runs also wait for the channel index, so this is a target time.
    RuleSuggestionResult:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - price_incl
        - price_excl
        - currency
        - original_price_incl
        - is_approved
        - approval_reason
        - min_price_applied
        - min_price_value
        - max_price_applied
        - max_price_value
        - status_message
        - created_at
      properties:
        id:
          type: integer
          minimum: 1
        status:
          type: string
          enum:
            - calculated
            - pending_approval
            - skipped
            - error
          description: "calculated: the rule sets price_incl; pending_approval: it will after someone approves it in Pricemind; skipped/error: the rule leaves the price (see status_message)."
        price_incl:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
        price_excl:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        original_price_incl:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: The product's price incl. VAT when the rule ran; the difference to price_incl is the change.
        is_approved:
          type: boolean
        approval_reason:
          type: string
          nullable: true
          description: Why approval is or is not needed, e.g. within_auto_approve_range or above_auto_approve_range.
        min_price_applied:
          type: boolean
          description: The rule's floor raised the price.
        min_price_value:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: The floor, excl. VAT, when the rule has one.
        max_price_applied:
          type: boolean
          description: The rule's ceiling lowered the price.
        max_price_value:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: The ceiling, excl. VAT, when the rule has one.
        status_message:
          type: string
          nullable: true
          description: Free text from the rule engine, e.g. why the product was skipped.
        created_at:
          type: string
          format: date-time
          pattern: Z$
          description: When the rule run produced this result, RFC3339 UTC.
    RuleSuggestion:
      type: object
      additionalProperties: false
      required:
        - rule
        - result
        - excluded_reason
      properties:
        rule:
          type: object
          additionalProperties: false
          required:
            - id
            - name
            - execution_mode
            - next_execution_at
          properties:
            id:
              type: integer
              minimum: 1
            name:
              type: string
            execution_mode:
              type: string
              enum:
                - scheduled
                - auto
                - manual
              description: scheduled runs at next_execution_at, auto after each index refresh, manual when someone starts it.
            next_execution_at:
              type: string
              nullable: true
              format: date-time
              pattern: Z$
              description: Next planned run of a scheduled rule, RFC3339 UTC; null for auto and manual rules. Scheduled runs also wait for the channel index, so this is a target time.
          nullable: true
        result:
          type: object
          additionalProperties: false
          required:
            - id
            - status
            - price_incl
            - price_excl
            - currency
            - original_price_incl
            - is_approved
            - approval_reason
            - min_price_applied
            - min_price_value
            - max_price_applied
            - max_price_value
            - status_message
            - created_at
          properties:
            id:
              type: integer
              minimum: 1
            status:
              type: string
              enum:
                - calculated
                - pending_approval
                - skipped
                - error
              description: "calculated: the rule sets price_incl; pending_approval: it will after someone approves it in Pricemind; skipped/error: the rule leaves the price (see status_message)."
            price_incl:
              type: string
              nullable: true
              pattern: ^-?[0-9]+\.[0-9]{2}$
              description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
            price_excl:
              type: string
              nullable: true
              pattern: ^-?[0-9]+\.[0-9]{2}$
              description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
            currency:
              type: string
              pattern: ^[A-Z]{3}$
            original_price_incl:
              type: string
              nullable: true
              pattern: ^-?[0-9]+\.[0-9]{2}$
              description: The product's price incl. VAT when the rule ran; the difference to price_incl is the change.
            is_approved:
              type: boolean
            approval_reason:
              type: string
              nullable: true
              description: Why approval is or is not needed, e.g. within_auto_approve_range or above_auto_approve_range.
            min_price_applied:
              type: boolean
              description: The rule's floor raised the price.
            min_price_value:
              type: string
              nullable: true
              pattern: ^-?[0-9]+\.[0-9]{2}$
              description: The floor, excl. VAT, when the rule has one.
            max_price_applied:
              type: boolean
              description: The rule's ceiling lowered the price.
            max_price_value:
              type: string
              nullable: true
              pattern: ^-?[0-9]+\.[0-9]{2}$
              description: The ceiling, excl. VAT, when the rule has one.
            status_message:
              type: string
              nullable: true
              description: Free text from the rule engine, e.g. why the product was skipped.
            created_at:
              type: string
              format: date-time
              pattern: Z$
              description: When the rule run produced this result, RFC3339 UTC.
          nullable: true
        excluded_reason:
          type: string
          nullable: true
          enum:
            - no_rule
            - in_campaign
            - not_in_scope
            - null
          description: "Set when no rule decides the price: no_rule (the channel has no active rule), in_campaign (an active campaign prices the product), not_in_scope (active rules have no current result for it). rule and result are then null."
      description: "The rule result that decides the product's price: an active campaign wins over rules; otherwise the highest-priority active rule whose latest result sets a price, else the highest-priority rule that skipped or failed. Superseded and rejected results never count. Approving stays in Pricemind."
    ProductSearchResult:
      type: object
      additionalProperties: false
      required:
        - product_domain_id
        - title
        - sku
        - ean
        - price
        - currency
      properties:
        product_domain_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: Decimal identity serialized as a string; never a legacy product_id.
        title:
          type: string
          nullable: true
        sku:
          type: string
          nullable: true
        ean:
          type: string
          nullable: true
        price:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: Current price incl. VAT in the channel currency.
        currency:
          type: string
          nullable: true
          pattern: ^[A-Z]{3}$
    ProductSearchResults:
      type: array
      items:
        $ref: "#/components/schemas/ProductSearchResult"
      description: Enabled channel products whose name, any product code (SKU, EAN, ...) or a global custom field contains q, ordered by name; at most limit.
    ManualUrlPreviewCode:
      type: object
      additionalProperties: false
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: Upper-case code name, e.g. EAN or SKU.
        value:
          type: string
    ManualUrlPreview:
      type: object
      additionalProperties: false
      required:
        - product_domain_id
        - title
        - url
        - domain
        - image
        - codes
        - brand
        - price
        - currency
        - availability
        - observed_at
        - code_matches
      properties:
        product_domain_id:
          type: integer
          minimum: 1
          nullable: true
          description: The checked page's product identity once it is saved; null while only a transformed preview exists.
        title:
          type: string
        url:
          type: string
        domain:
          type: string
        image:
          type: string
          description: Image URL, or an empty string.
        codes:
          type: array
          items:
            $ref: "#/components/schemas/ManualUrlPreviewCode"
        brand:
          type: string
          nullable: true
        price:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
        currency:
          type: string
        availability:
          $ref: "#/components/schemas/CatalogAvailability"
        observed_at:
          type: string
          nullable: true
          format: date-time
          pattern: Z$
          description: When the price above was read, RFC3339 UTC.
        code_matches:
          type: array
          items:
            type: string
            description: A global code name equal on the page and your product, e.g. EAN.
      description: What the check read from the page, for the person to compare with their product before confirming.
    ManualUrlFailure:
      type: object
      additionalProperties: false
      required:
        - code
        - title
        - message
      properties:
        code:
          type: string
        title:
          type: string
        message:
          type: string
      description: Why the check stopped, with Lobe's copy. Retry when can_retry.
    ManualUrlWorkflow:
      type: object
      additionalProperties: false
      required:
        - id
        - state
        - version
        - submitted_url
        - preview
        - headline
        - detail
        - progress
        - can_confirm
        - can_retry
        - terminal
        - in_progress
        - failure
      properties:
        id:
          type: string
          format: uuid
        state:
          type: string
          enum:
            - dispatching
            - queued
            - crawling
            - extracting
            - ready_for_review
            - confirming
            - confirmed
            - cancelled
            - superseded
            - dispatch_failed
            - completed_without_product
            - failed
            - timed_out
        version:
          type: integer
          minimum: 1
        submitted_url:
          type: string
          description: The normalized page URL that is checked.
        preview:
          type: object
          additionalProperties: false
          required:
            - product_domain_id
            - title
            - url
            - domain
            - image
            - codes
            - brand
            - price
            - currency
            - availability
            - observed_at
            - code_matches
          properties:
            product_domain_id:
              type: integer
              minimum: 1
              nullable: true
              description: The checked page's product identity once it is saved; null while only a transformed preview exists.
            title:
              type: string
            url:
              type: string
            domain:
              type: string
            image:
              type: string
              description: Image URL, or an empty string.
            codes:
              type: array
              items:
                $ref: "#/components/schemas/ManualUrlPreviewCode"
            brand:
              type: string
              nullable: true
            price:
              type: string
              nullable: true
              pattern: ^-?[0-9]+\.[0-9]{2}$
              description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
            currency:
              type: string
            availability:
              $ref: "#/components/schemas/CatalogAvailability"
            observed_at:
              type: string
              nullable: true
              format: date-time
              pattern: Z$
              description: When the price above was read, RFC3339 UTC.
            code_matches:
              type: array
              items:
                type: string
                description: A global code name equal on the page and your product, e.g. EAN.
          description: What the check read from the page, for the person to compare with their product before confirming.
          nullable: true
        headline:
          type: string
          description: Lobe's status headline, e.g. Product ready — your turn.
        detail:
          type: string
        progress:
          type: integer
          minimum: 0
          maximum: 100
        can_confirm:
          type: boolean
        can_retry:
          type: boolean
        terminal:
          type: boolean
        in_progress:
          type: boolean
          description: Something is still moving; poll the status.
        failure:
          type: object
          additionalProperties: false
          required:
            - code
            - title
            - message
          properties:
            code:
              type: string
            title:
              type: string
            message:
              type: string
          description: Why the check stopped, with Lobe's copy. Retry when can_retry.
          nullable: true
      description: "Lobe's manual URL check: the page is crawled (or a fresh known price is reused), shown for review, and matched to the product only after a person confirms it. Crawl failures are reported in failure, not as HTTP errors. Send version back on confirm and retry."
    ManualUrlStart:
      type: object
      additionalProperties: false
      required:
        - url
        - product_domain_id
      properties:
        url:
          type: string
          maxLength: 2048
          description: The competitor product page. Its shop must be a competitor of the channel.
        product_domain_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: Decimal identity serialized as a string; never a legacy product_id.
      description: Start checking a competitor page for one of your products.
    ManualUrlAction:
      type: object
      additionalProperties: false
      required: []
      properties:
        version:
          type: integer
          minimum: 1
      description: version is required for confirm and retry; cancel retires the check whatever its version.
    ProductHistoryPoint:
      type: object
      additionalProperties: false
      required:
        - t
        - price
        - regular
      properties:
        t:
          type: string
          format: date-time
          pattern: Z$
          description: Observation time, RFC3339 UTC; in weekly windows the week's last observation.
        price:
          type: string
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: "The price on the window's basis: the special price when set, else the regular price, in the channel currency."
        regular:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: The regular price at that point; null when unknown.
    ProductHistoryHolder:
      type: object
      additionalProperties: false
      required:
        - from
        - to
        - vendor
        - is_own
      properties:
        from:
          type: string
          format: date-time
          pattern: Z$
          description: First crawl this seller held the buy box.
        to:
          type: string
          nullable: true
          format: date-time
          pattern: Z$
          description: The crawl another seller took it; null for the current holder.
        vendor:
          type: string
          description: The seller's name as the marketplace shows it.
        is_own:
          type: boolean
          description: The seller is your configured marketplace seller name (trimmed, case-insensitive).
    ProductHistorySeries:
      type: object
      additionalProperties: false
      required:
        - key
        - role
        - offer_id
        - domain
        - seller_name
        - color
        - set_aside
        - ends_at
        - points
      properties:
        key:
          type: string
          description: own, the competitor offer's offer_id, buybox:{page product_domain_id} or own_marketplace:{page product_domain_id}. Events and special prices refer to it.
        role:
          type: string
          enum:
            - own
            - competitor
            - buy_box
            - own_marketplace
          description: "own: your price (out-of-stock prices stay drawn). competitor: one matched non-marketplace offer (non-eMAG marketplace pages too, from the page price). buy_box: one eMAG page (emag.bg, emag.ro, emag.hu) from the page price, which is the buy-box price. own_marketplace: your seller's offer on that eMAG page, present only when your seller name is configured and you were on the page in the window."
        offer_id:
          type: string
          pattern: ^v1\.[A-Za-z0-9_-]+$
          description: "The resolve offer the line belongs to: null for own; for buy_box the seller offer selected for comparison (null when none); for own_marketplace your current seller offer, null once you have left the page."
          nullable: true
        domain:
          type: string
        seller_name:
          type: string
          nullable: true
          description: "buy_box: the current holder; own_marketplace: your seller name; otherwise null."
        color:
          type: string
          pattern: ^#[0-9a-f]{6}$
          description: "Lobe's chart colour for the line; own and own_marketplace are always #6366f1."
        set_aside:
          type: string
          nullable: true
          enum:
            - out_of_stock
            - stale
            - not_comparable
            - no_price
            - null
          description: "Why the panel sets the offer aside now, by the same rule as resolve's offers; null when it is compared. Always null for own. own_marketplace after you left the page: no_price."
        ends_at:
          type: string
          nullable: true
          format: date-time
          pattern: Z$
          description: The line's last good point when it stops (set_aside is set); lines are never filled across gaps.
        own_seller_configured:
          type: boolean
          description: "buy_box only: whether your seller name on this marketplace is configured in the channel."
        holders:
          type: array
          items:
            $ref: "#/components/schemas/ProductHistoryHolder"
          description: "buy_box only: who held the buy box, as contiguous intervals from every crawl in the window (also in weekly windows), oldest first."
        points:
          type: array
          items:
            $ref: "#/components/schemas/ProductHistoryPoint"
          description: In-stock observations with a price, oldest first.
    ProductHistoryExtreme:
      type: object
      additionalProperties: false
      required:
        - offer_id
        - price
        - since
      properties:
        offer_id:
          type: string
          pattern: ^v1\.[A-Za-z0-9_-]+$
          description: The comparable offer, possibly an eMAG seller without a line; name it from resolve's offers.
        price:
          type: string
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
        since:
          type: string
          format: date-time
          pattern: Z$
          description: When that offer's run at this price began.
      description: The lowest or highest price any comparable offer had in the window, at its most recent occurrence.
    ProductHistorySummary:
      type: object
      additionalProperties: false
      required:
        - comparable_count
        - average_now
        - lowest
        - highest
      properties:
        comparable_count:
          type: integer
          minimum: 0
          description: The panel verdict's comparable offers, including eMAG sellers without a line and your own marketplace seller row when resolve lists it.
        average_now:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: Average current price of the comparable offers; null when there are none.
        lowest:
          type: object
          additionalProperties: false
          required:
            - offer_id
            - price
            - since
          properties:
            offer_id:
              type: string
              pattern: ^v1\.[A-Za-z0-9_-]+$
              description: The comparable offer, possibly an eMAG seller without a line; name it from resolve's offers.
            price:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{2}$
              description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
            since:
              type: string
              format: date-time
              pattern: Z$
              description: When that offer's run at this price began.
          description: The lowest or highest price any comparable offer had in the window, at its most recent occurrence.
          nullable: true
        highest:
          type: object
          additionalProperties: false
          required:
            - offer_id
            - price
            - since
          properties:
            offer_id:
              type: string
              pattern: ^v1\.[A-Za-z0-9_-]+$
              description: The comparable offer, possibly an eMAG seller without a line; name it from resolve's offers.
            price:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{2}$
              description: Customer-visible monetary amount rounded half-up to two decimal places, matching Lobe. Null is unknown; zero is a known zero.
            since:
              type: string
              format: date-time
              pattern: Z$
              description: When that offer's run at this price began.
          description: The lowest or highest price any comparable offer had in the window, at its most recent occurrence.
          nullable: true
    ProductHistorySpecialPrice:
      type: object
      additionalProperties: false
      required:
        - key
        - discount_percent
        - from
        - to
      properties:
        key:
          type: string
          description: The series key.
        discount_percent:
          type: string
          pattern: ^[0-9]+\.[0-9]$
          description: Discount below the regular price at the period's latest point, one decimal.
        from:
          type: string
          format: date-time
          pattern: Z$
          description: First point on special; earlier than the window's from when the special was already running before it.
        to:
          type: string
          nullable: true
          format: date-time
          pattern: Z$
          description: The point the special ended; null while it lasts, or the line's ends_at when the line stopped.
    ProductHistoryEvent:
      type: object
      additionalProperties: false
      required:
        - at
        - key
        - type
        - from
        - to
        - promo
      properties:
        at:
          type: string
          format: date-time
          pattern: Z$
        key:
          type: string
          description: The series key.
        type:
          type: string
          enum:
            - price_drop
            - price_up
            - out_of_stock
            - back_in_stock
            - buy_box_change
        from:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: The price before; for buy_box_change the outgoing holder's price at its last crawl.
        to:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: The price after (null for out_of_stock); for buy_box_change the new holder's price.
        promo:
          type: string
          nullable: true
          enum:
            - started
            - ended
            - null
          description: A special price began or ended with this change.
        from_vendor:
          type: string
          description: "buy_box_change only: the outgoing holder."
        to_vendor:
          type: string
          description: "buy_box_change only: the new holder."
        from_is_own:
          type: boolean
          description: buy_box_change only.
        to_is_own:
          type: boolean
          description: buy_box_change only.
        own_price:
          type: string
          nullable: true
          pattern: ^-?[0-9]+\.[0-9]{2}$
          description: "buy_box_change only: your seller's price on the page at that crawl; null when you were not on it or out of stock."
    ProductHistory:
      type: object
      additionalProperties: false
      required:
        - range
        - from
        - to
        - resolution
        - currency
        - basis
        - series
        - summary
        - special_prices
        - events
        - events_truncated
      properties:
        range:
          type: string
          enum:
            - 1w
            - 2w
            - 1m
            - 2m
            - 3m
            - 6m
            - 12m
        from:
          type: string
          format: date-time
          pattern: Z$
          description: 00:00 UTC of the window's first day.
        to:
          type: string
          format: date-time
          pattern: Z$
          description: 23:59:59 UTC today; the window includes today.
        resolution:
          type: string
          enum:
            - observation
            - week
          description: "observation: every observation (1w to 2m). week: each Monday-aligned UTC week's last observation (3m, 6m, 12m); price events follow the weeks, buy-box holders and buy_box_change stay per crawl."
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        basis:
          type: string
          enum:
            - incl
            - excl
        series:
          type: array
          items:
            $ref: "#/components/schemas/ProductHistorySeries"
          description: "own first, then by domain: buy_box before own_marketplace on each eMAG page."
        summary:
          $ref: "#/components/schemas/ProductHistorySummary"
        special_prices:
          type: array
          items:
            $ref: "#/components/schemas/ProductHistorySpecialPrice"
          description: Periods with a special price below the regular price, newest first.
        events:
          type: array
          items:
            $ref: "#/components/schemas/ProductHistoryEvent"
          maxItems: 500
          description: Newest first, at most 500.
        events_truncated:
          type: boolean
          description: There were more than 500 events.
      description: "The browser companion's price history window: your price, one line per matched offer, the eMAG buy box with who held it and your own eMAG offer, a summary over the panel's comparable offers, special-price periods and events. Events and special prices at the window's start compare with each line's last observation in the 30 days before it, which is never a point. Prices are in the channel currency on the requested basis; the payload carries no labels."
  examples:
    ErrorExamples:
      missing_api_key:
        summary: Missing API key
        value:
          error: missing API key
      invalid_api_key:
        summary: Invalid API key
        value:
          error: invalid API key
      key_revoked:
        summary: API key revoked
        value:
          error: key revoked
      key_expired:
        summary: API key expired
        value:
          error: key expired
      invalid_request:
        summary: Invalid request body
        value:
          error: invalid request body
      missing_required_fields:
        summary: Missing required fields
        value:
          error: product_sku and price are required
      channel_not_found:
        summary: Channel not found
        value:
          error: channel not found or access denied
      product_not_found:
        summary: Product not found
        value:
          error: product not found
      no_active_source:
        summary: No active channel source
        value:
          error: no active channel source
      internal_error:
        summary: Internal server error
        value:
          error: failed to insert price
tags:
  - name: Health
    description: Health check endpoints
  - name: Channels
    description: Channel management operations
  - name: Prices
    description: Product price management operations
  - name: Sources
    description: Channel source selection, synchronization state, and durable run operations
  - name: Crawls
    description: Generic channel-authorized tracked crawl operations
  - name: Channel catalog
    description: Current own products and their selected matched competitor offers.
  - name: Browser companion
    description: "Reads for the Pricemind browser companion: which of your products a shop page belongs to and how it is priced."
x-pricemind-docs-provenance:
  sourceRepository: git@gitlab.com:stellion/pricemind/api/core-api.git
  sourceRef: origin/develop
  sourceCommit: 8d5a790edb9155b48d5485ed80fd00feaba6aaa6
  sourcePath: openapi.json
  sourceSha256: 146aadeb515366edc37a37c359073e50aefcc903e46177cfb32eb6320578564a
  normalizationOverlay: content/openapi/docs-overlay.json
