{
  "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.\n\nIf the API key is associated with a platform integration (e.g., Magento), \nthis endpoint returns only channels that are connected to that specific integration.\n\nIf the API key is not associated with any integration, it returns all channels \nowned by the user.\n\nThis endpoint automatically scopes the results based on the API key's integration context,\nmaking it suitable for both general API usage and platform integrations.\n",
        "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.\n\nThis endpoint allows you to set pricing information for products including:\n- Base price\n- Special/discounted price\n- Delivery costs\n- Tax information\n\nThe system will automatically calculate tax-inclusive and tax-exclusive prices based on the provided tax rate.\n\nAfter creating a price, the system will trigger an asynchronous reindex operation to update search indexes.\n",
        "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\ncompatibility route remains available to existing legacy credentials.\nNew integrations should prefer the channel-scoped source routes. Source\nconfiguration is deliberately omitted because it may contain credentials\nor authenticated feed URLs.\n",
        "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.\nSource configuration is deliberately omitted from the response.\n",
        "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\ncompatibility route remains available to legacy credentials. The\nresponse distinguishes source selection (`selected`) from source-sync\neligibility (`sync.enabled` and `sync.disabled`).\n",
        "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\nshould use `/sources/selected` for the source selected by the channel;\nselection and source-sync enablement are independent states.\n",
        "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`.\nRequires `sources:read`. This is selection state only: inspect `sync`\nto determine whether source synchronization is enabled and scheduled.\n",
        "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.\nRequires `sources:read`. The response never exposes the source `config`;\nuse `selected`, `sync`, and `latest_run` for safe operational state.\n",
        "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\ndurable numeric dispatch-ledger ID. Requires `sources:run`; legacy API\nkeys do not inherit this permission. Manual API runs do not require the\nsource to be selected, scheduled, or enabled for scheduled synchronization.\nRunnable source types are `magento`, `shopify`, `senteca`, `feed`, and `file`;\nother source types return `409 source_type_not_runnable`. Poll the returned\n`Location` or use the run-list route for progress.\n",
        "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\n`sources:read`. Pass the returned `next_cursor` value as the `cursor`\nquery parameter to fetch the next page.\n",
        "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\nscope. Requires `sources:read`. The numeric `source_run_id` identifies\nthe dispatch-ledger occurrence and remains stable across retries.\n",
        "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,\na direct batch of at most 100 exact targets, or an authorized saved\nsegment snapshotted server-side. Segment snapshots are durably\nidempotent within the authoritative account, channel, and actor scope:\nan exact segment retry reuses one transfer while a changed segment,\ntarget set, or reason under the same key returns 409. Channel-runner\nseparately binds the complete crawl request. Requires the `crawl:run`\nscope. Trusted MCP calls use a server-bound two-step confirmation; this\nschema documents the direct REST write.\n",
        "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.\n\nCanonical 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\nintentionally omitted because it can contain credentials, bearer\ntokens, signed URLs, or other provider secrets. `selected` reports\nchannel selection; it does not imply that synchronization is enabled.\n",
        "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\nthe inverse convenience view of the persisted `disabled` flag. This flag\ncontrols scheduled synchronization only; explicitly authorized manual\nAPI runs remain available. Scheduled runs additionally require a schedule\nand due `next_run`.\n",
        "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\ndispatch-ledger identity and remains stable if the dispatch is retried\nwith different downstream spider, crawl, or import links.\n",
        "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\nlinked; zero is meaningful and is not the same as unavailable.\n",
        "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.\nMust be a valid decimal number greater than 0.\n",
            "pattern": "^\\d+(\\.\\d+)?$",
            "example": "29.99"
          },
          "special_price": {
            "type": "string",
            "nullable": true,
            "description": "Special/discounted price as a decimal string.\nMust be less than the base price.\n",
            "pattern": "^\\d+(\\.\\d+)?$",
            "example": "24.99"
          },
          "delivery_price": {
            "type": "string",
            "nullable": true,
            "description": "Delivery/shipping cost as a decimal string.\n",
            "pattern": "^\\d+(\\.\\d+)?$",
            "example": "5.99"
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "description": "Currency code (ISO 4217).\nIf not provided, uses the channel's default currency.\n",
            "minLength": 3,
            "maxLength": 3,
            "example": "USD"
          },
          "includes_tax": {
            "type": "boolean",
            "description": "Whether the provided prices include tax.\nIf true, tax will be calculated and removed from the stored price.\nIf false, tax will be calculated and added to create tax-inclusive prices.\n",
            "default": false,
            "example": false
          },
          "tax_rate": {
            "type": "string",
            "nullable": true,
            "description": "Tax rate as a decimal string (e.g., 0.20 for 20%).\nIf not provided, uses the channel's default VAT rate.\n",
            "pattern": "^\\d+(\\.\\d+)?$",
            "example": "0.20"
          },
          "origin": {
            "type": "string",
            "nullable": true,
            "description": "Origin of the price data.\nUsed for tracking the source of price information.\n",
            "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"
  }
}
