{ "openapi": "3.0.3", "info": { "title": "affilinode API", "summary": "Product data, prices, comparisons and reporting for websites and your own applications", "description": "With the affilinode API you read products with current offers and affiliate links, comparisons, lists, catalog data, coupons and reports from your account – for your website, an app or your own tools. You can also request products that are not in the catalog yet and create short links.\n\n## Access\n\nEvery request needs a key from your account (keys start with `ac_`). There are two kinds:\n\n- **Site keys** belong to a website. They may use all routes described here, except the attribute import. The links in the responses carry that website’s tracking IDs.\n- **API clients** are meant for your own applications. You give each client only the permissions it needs:\n\n| Permission | allows |\n| --- | --- |\n| `products:read` | Products with prices, offers and affiliate links, comparisons, lists, search, coupons, banners |\n| `catalog:read` | Catalog data (product types, attributes, views, changes, compatibility, advisors) without affiliate links |\n| `products:write` | Import attributes (datasheet values) for products in your account |\n| `requests:write` | Create and manage product requests |\n| `reporting:read` | Reporting (clicks, orders, revenue) |\n\nSend the key in the header `Authorization: Bearer ac_…`; `X-API-Key: ac_…` works as an alternative. Each route names the permission an API client needs for it.\n\n## Language and country\n\n`locale` (for example `de-DE`) selects the language of the texts, `country` (for example `DE`) the country for offers, prices and availability. They are independent: `country=AT&locale=de-DE` returns German texts with Austrian offers. Without them the defaults of your website or account apply. If a text is missing in the requested language, the next best one is delivered; `textLocales` shows which language a text has.\n\nWith `shops` and `prefer` you can override the shop rules per request (see the route parameters).\n\n## Product identifiers\n\nWherever a product is expected you can use the affilinode ID or an identifier of the product: `asin:B0CHX1W1XY`, `gtin:4006381333931` or `mpn:bosch/06019H5202` (brand and model number). Separate several identifiers with commas (at most 50).\n\n## Plan\n\nSome features are not part of every plan. `GET /v1/me` shows what your plan includes in the field `planFeatures`. If a key calls a feature that the plan does not include, the API responds with status 402 or 403.\n\n## Errors\n\nErrors come with a fitting HTTP status and this structure:\n\n```json\n{ \"error\": { \"code\": \"validation_failed\", \"message\": \"Die Anfrage ist ungültig\", \"details\": [] } }\n```\n\nEvaluate the `code`; the `message` is meant for humans and is in German.\n\n## Rate limiting\n\nThe number of requests per minute is limited per key. Responses carry the headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. When the limit is exceeded the API responds with status 429 and the header `Retry-After` (seconds until you can try again).\n\n## Caching\n\nResponses to GET requests carry an `ETag`. If you send it with the next request as `If-None-Match`, the API responds with status 304 and no content when the data is unchanged. Responses contain links with your tracking IDs and may therefore only be cached privately.\n\n## Several subsites (WordPress multisite)\n\nA network of several WordPress sites uses one site key. With the optional headers `X-AC-Blog`, `X-AC-Blog-Name` and `X-AC-Blog-Url` you say which subsite is asking so that its tracking IDs end up in the links.\n\n## Trying it out in the browser\n\nThe documentation on affilinode.com can call read-only routes (GET) directly with your key. The key stays in your browser.", "version": "1.0.2", "contact": { "name": "affilinode support", "url": "https://affilinode.com", "email": "support@affilinode.com" } }, "servers": [ { "url": "https://api.affilinode.com", "description": "Public API" } ], "tags": [ { "name": "Account", "description": "Connection test: which account does the key belong to and what may it do?" }, { "name": "Products", "description": "Products with offers, prices and affiliate links. Also spare parts, accessories, plans, contract offers and the price history of a product." }, { "name": "Comparisons", "description": "Compare products side by side: comparison, A versus B, saved comparison tables and comparison data." }, { "name": "Lists", "description": "Editorial and automatic product lists (top lists, bestsellers)." }, { "name": "Deals and coupons", "description": "Price drops, coupons and discount codes, and the report that a code was copied." }, { "name": "Search", "description": "Product search by title, brand and identifiers, and search with filters." }, { "name": "Catalog", "description": "Catalog data without affiliate links: product types with attributes, products of a product type, views, changes since a point in time, product pairs and compatibility." }, { "name": "Guidance and recommendations", "description": "Alternatives, similar products, strengths, top lists per product type, value-for-money charts and the product advisor (buying-guide quiz)." }, { "name": "Banners, looks and cart", "description": "Banners from partner programs, Shop-my-Look images and cart links for several products." }, { "name": "Product requests", "description": "Request products that are not in the catalog yet. The request is processed in the background; you query its state or wait briefly for the result." }, { "name": "Reporting", "description": "Clicks, impressions, orders and revenue from your partner programs." }, { "name": "Short links", "description": "Create short links for social media and messengers." } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "paths": { "/v1/me": { "get": { "tags": [ "Account" ], "summary": "Check the connection", "description": "Returns the account behind your key, the kind of key (site or API client with its permissions), the features of your plan and the balance for AI features. A good first test that your key works.\n\nThis route is open to every valid key.", "operationId": "getMe", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "slug", "name" ], "additionalProperties": false }, "features": { "type": "array", "items": { "type": "string" } }, "principal": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "defaultCountry": { "type": "string" }, "defaultLocale": { "type": "string" } }, "required": [ "type", "id", "name", "defaultCountry", "defaultLocale" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_client" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "products:read", "requests:write", "catalog:read", "reporting:read", "products:write" ] } } }, "required": [ "type", "id", "name", "scopes" ], "additionalProperties": false } ] }, "policies": { "default": { "amazonAssociate": false }, "type": "object", "properties": { "amazonAssociate": { "type": "boolean" } }, "required": [ "amazonAssociate" ], "additionalProperties": false }, "planFeatures": { "default": null, "nullable": true, "type": "array", "items": { "type": "string" } }, "staleShops": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "offers": { "type": "integer" }, "stale": { "type": "integer" }, "newestCheck": { "nullable": true, "type": "string" }, "stuck": { "type": "boolean" } }, "required": [ "name", "type", "offers", "stale", "newestCheck", "stuck" ], "additionalProperties": false } }, "credits": { "default": null, "nullable": true, "type": "object", "properties": { "unmetered": { "type": "boolean" }, "available": { "type": "integer" }, "lowBalance": { "type": "boolean" } }, "required": [ "unmetered", "available", "lowBalance" ], "additionalProperties": false }, "poweredBy": { "default": false, "type": "boolean" } }, "required": [ "tenant", "features", "principal", "policies", "planFeatures", "staleShops", "credits", "poweredBy" ], "additionalProperties": false }, "example": { "tenant": { "id": "2f6c8e1a-3b4d-4c5e-9a0b-1c2d3e4f5a6b", "slug": "mein-blog", "name": "Mein Blog" }, "features": [ "products", "compare", "lists", "search" ], "principal": { "type": "site", "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "name": "meinblog.example", "defaultCountry": "DE", "defaultLocale": "de-DE", "fallbackRouting": null, "geoRouting": null, "allowedCountries": null }, "policies": { "amazonAssociate": false }, "planFeatures": null, "staleShops": [], "credits": { "unmetered": false, "available": 120, "lowBalance": false }, "poweredBy": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products": { "get": { "tags": [ "Products" ], "summary": "Get products", "description": "Returns products for the given identifiers: title, images, attributes, texts and the shops’ offers with prices and affiliate links (including your tracking IDs). This is the route for buy buttons, price comparisons and product boxes.\n\n`resolved` shows which requested identifier belongs to which product; identifiers without a match are listed in `missing`. If you request a product that still needs offers, affilinode looks for them in the background – a later request returns them.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "ids", "required": true, "description": "Product identifiers, comma-separated (at most 50): the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`. Duplicates are merged.", "example": "asin:B0CHX1W1XY,gtin:4006381333931" }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "activate", "required": false, "description": "With `false` the products are only looked up and not scheduled for ongoing price updates. Meant for matching very many identifiers at once (bulk matching). Default: `true`." }, { "schema": { "type": "string", "enum": [ "queue" ] }, "in": "query", "name": "search", "required": false, "description": "Only together with `activate=false`: `queue` adds the products to an occasional, slow offer search." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies.", "example": "de-DE" }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies.", "example": "DE" }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "The products with offers", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "resolved": { "type": "object", "additionalProperties": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } } }, "required": [ "products", "resolved", "missing" ], "additionalProperties": false }, "example": { "products": [ { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "detailedTitle": null, "brand": "Nova", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null } ], "resolved": { "asin:B0CHX1W1XY": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "gtin:4006381333931": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42" }, "missing": [] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/spare-parts": { "get": { "tags": [ "Products" ], "summary": "Spare parts of a product", "description": "Returns the spare parts that fit a device, grouped. `fitsProductIds` lists the devices the product itself fits as a spare part.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getProductSpareParts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Product identifier: the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "productIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "label", "productIds" ], "additionalProperties": false } }, "fitsProductIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "productId", "groups", "fitsProductIds" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/accessories": { "get": { "tags": [ "Products" ], "summary": "Accessories of a product", "description": "Returns matching accessories for a product, grouped. `accessoryForProductIds` lists the products the product itself is an accessory for.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getProductAccessories", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Product identifier: the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "productIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "note": { "nullable": true, "type": "string" } }, "required": [ "productId", "note" ], "additionalProperties": false } } }, "required": [ "label", "productIds", "items" ], "additionalProperties": false } }, "accessoryForProductIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "productId", "groups", "accessoryForProductIds" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/tariffs": { "get": { "tags": [ "Products" ], "summary": "Plans for a device", "description": "Returns the mobile plans for a device (for example a smartphone) with term, monthly and one-off costs and the effective cost over the term.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getProductTariffs", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Device identifier: the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of plans (1 to 20). Default: 10." }, { "schema": { "default": "effective", "type": "string", "enum": [ "effective", "monthly", "upfront" ] }, "in": "query", "name": "sort", "required": false, "description": "Sorting: `effective` (effective cost, default), `monthly` (monthly price) or `upfront` (one-off costs)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 60 }, "in": "query", "name": "provider", "required": false, "description": "Only plans from this provider, for example `Telekom`." }, { "schema": { "type": "string", "enum": [ "telekom", "vodafone", "o2", "1und1" ] }, "in": "query", "name": "network", "required": false, "description": "Only plans on this network: `telekom`, `vodafone`, `o2` or `1und1`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductWithReplacement" }, "tariffs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "shop": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false }, "url": { "type": "string" }, "title": { "nullable": true, "type": "string" }, "provider": { "nullable": true, "type": "string" }, "providerInfo": { "default": null, "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slug": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "network_operator", "brand", "discounter", "reseller", "mvno" ] }, "logoUrl": { "nullable": true, "type": "string" }, "website": { "nullable": true, "type": "string" }, "parentCompany": { "nullable": true, "type": "string" } }, "required": [ "id", "slug", "name", "kind", "logoUrl", "website", "parentCompany" ], "additionalProperties": false }, "network": { "nullable": true, "type": "string", "enum": [ "telekom", "vodafone", "o2", "1und1" ] }, "promo": { "default": null, "nullable": true, "type": "object", "properties": { "price": { "$ref": "#/components/schemas/Money" }, "months": { "nullable": true, "type": "integer" }, "validUntil": { "nullable": true, "type": "string" } }, "required": [ "price", "months", "validUntil" ], "additionalProperties": false }, "smsPrice": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "throttleNote": { "default": null, "nullable": true, "type": "string" }, "lte": { "default": null, "nullable": true, "type": "boolean" }, "maxDownloadMbit": { "default": null, "nullable": true, "type": "integer" }, "maxUploadMbit": { "default": null, "nullable": true, "type": "integer" }, "euRoaming": { "default": null, "nullable": true, "type": "boolean" }, "euRoamingGb": { "default": null, "nullable": true, "type": "number" }, "wifiCalling": { "default": null, "nullable": true, "type": "boolean" }, "volte": { "default": null, "nullable": true, "type": "boolean" }, "esim": { "default": null, "nullable": true, "type": "boolean" }, "multiSim": { "default": null, "nullable": true, "type": "boolean" }, "hotspot": { "default": null, "nullable": true, "type": "boolean" }, "streamingNote": { "default": null, "nullable": true, "type": "string" }, "bonus": { "default": null, "nullable": true, "type": "object", "properties": { "amount": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "note": { "nullable": true, "type": "string" } }, "required": [ "amount", "note" ], "additionalProperties": false }, "cancellationNote": { "default": null, "nullable": true, "type": "string" }, "providerNote": { "default": null, "nullable": true, "type": "string" }, "source": { "default": "feed", "type": "string", "enum": [ "feed", "manual" ] }, "tariffName": { "nullable": true, "type": "string" }, "dataGb": { "nullable": true, "type": "number" }, "unlimitedData": { "type": "boolean" }, "allnetFlat": { "nullable": true, "type": "boolean" }, "smsFlat": { "nullable": true, "type": "boolean" }, "fiveG": { "nullable": true, "type": "boolean" }, "contractMonths": { "nullable": true, "type": "integer" }, "upfrontPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "monthlyPrice": { "$ref": "#/components/schemas/Money" }, "connectionFee": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "totalCost": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "effectiveMonthly": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "checkedAt": { "nullable": true, "type": "string" } }, "required": [ "id", "shop", "url", "title", "provider", "providerInfo", "network", "promo", "smsPrice", "throttleNote", "lte", "maxDownloadMbit", "maxUploadMbit", "euRoaming", "euRoamingGb", "wifiCalling", "volte", "esim", "multiSim", "hotspot", "streamingNote", "bonus", "cancellationNote", "providerNote", "source", "tariffName", "dataGb", "unlimitedData", "allnetFlat", "smsFlat", "fiveG", "contractMonths", "upfrontPrice", "monthlyPrice", "connectionFee", "totalCost", "effectiveMonthly", "checkedAt" ], "additionalProperties": false } } }, "required": [ "product", "tariffs" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/contract-offers": { "get": { "tags": [ "Products" ], "summary": "Contract offers for a product", "description": "Returns the providers’ offers for a contract product (internet, electricity, gas, streaming subscription) with term, prices and effective cost.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getProductContractOffers", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Contract product identifier: the affilinode ID or `gtin:…`, `mpn:brand/model`." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of offers (1 to 20). Default: 10." }, { "schema": { "default": "effective", "type": "string", "enum": [ "effective", "monthly", "total" ] }, "in": "query", "name": "sort", "required": false, "description": "Sorting: `effective` (effective cost, default), `monthly` (monthly price) or `total` (total cost over the term)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "in": "query", "name": "provider", "required": false, "description": "Only offers from this provider." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 60 }, "in": "query", "name": "maxTermMonths", "required": false, "description": "Maximum contract term in months (0 to 60)." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10000 }, "in": "query", "name": "minMbit", "required": false, "description": "Minimum speed in Mbit/s (for internet contracts)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductWithReplacement" }, "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "family": { "type": "string", "enum": [ "internet_dsl", "strom", "gas", "streaming_abo" ] }, "provider": { "nullable": true, "type": "string" }, "title": { "nullable": true, "type": "string" }, "url": { "type": "string" }, "priceKind": { "type": "string", "enum": [ "monthly", "yearly", "one_time" ] }, "amount": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "setupFee": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "termMonths": { "nullable": true, "type": "integer" }, "promo": { "nullable": true, "type": "object", "properties": { "phases": { "type": "array", "items": { "type": "object", "properties": { "months": { "type": "integer" }, "amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "months", "amount" ], "additionalProperties": false } }, "validUntil": { "nullable": true, "type": "string" }, "bonus": { "nullable": true, "type": "object", "properties": { "amount": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "note": { "nullable": true, "type": "string" } }, "required": [ "amount", "note" ], "additionalProperties": false } }, "required": [ "phases", "validUntil", "bonus" ], "additionalProperties": false }, "kind": { "type": "string", "enum": [ "offer", "compare" ] }, "totalCost": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "totalCostWithBonus": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "effectiveMonthly": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "effectiveMonthlyWithBonus": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "bonusAmount": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "horizonMonths": { "nullable": true, "type": "integer" }, "regularMonthly": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "attributes": { "type": "object", "additionalProperties": {} }, "facts": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "label", "value" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "feed", "manual" ] }, "checkedAt": { "nullable": true, "type": "string" } }, "required": [ "id", "family", "provider", "title", "url", "priceKind", "amount", "setupFee", "termMonths", "promo", "kind", "totalCost", "totalCostWithBonus", "effectiveMonthly", "effectiveMonthlyWithBonus", "bonusAmount", "horizonMonths", "regularMonthly", "attributes", "facts", "source", "checkedAt" ], "additionalProperties": false } }, "bonusDefault": { "default": false, "type": "boolean" } }, "required": [ "product", "offers", "bonusDefault" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/price-history": { "get": { "tags": [ "Products" ], "summary": "Price history of a product", "description": "Returns the price history of the last days with the course per day, the lowest price per shop and a summary (current, lowest, highest and average price). Shops whose prices must not be used are left out and listed in `excludedShopTypes`.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getProductPriceHistory", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Product identifier: the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "default": 90, "type": "integer", "minimum": 7, "maximum": 365 }, "in": "query", "name": "days", "required": false, "description": "Period in days (7 to 365). Default: 90." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "detailedTitle": { "default": null, "nullable": true, "type": "string" } }, "required": [ "id", "title", "detailedTitle" ], "additionalProperties": false }, "country": { "type": "string" }, "locale": { "type": "string" }, "currency": { "nullable": true, "type": "string" }, "days": { "type": "integer" }, "from": { "type": "string" }, "to": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "properties": { "shop": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] }, "name": { "type": "string" }, "logoUrl": { "nullable": true, "type": "string" }, "own": { "type": "boolean" } }, "required": [ "id", "type", "name", "logoUrl", "own" ], "additionalProperties": false }, "current": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "price": { "type": "number" }, "total": { "type": "number" }, "availability": { "type": "string", "enum": [ "in_stock", "limited", "preorder", "out_of_stock", "unknown" ] } }, "required": [ "date", "price", "total", "availability" ], "additionalProperties": false } } }, "required": [ "shop", "current", "points" ], "additionalProperties": false } }, "best": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "total": { "type": "number" }, "shopId": { "type": "string" } }, "required": [ "date", "total", "shopId" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "current": { "nullable": true, "type": "object", "properties": { "total": { "$ref": "#/components/schemas/Money" }, "shopId": { "type": "string" }, "shopName": { "type": "string" }, "checkedAt": { "type": "string" } }, "required": [ "total", "shopId", "shopName", "checkedAt" ], "additionalProperties": false }, "lowest": { "nullable": true, "type": "object", "properties": { "total": { "$ref": "#/components/schemas/Money" }, "date": { "type": "string" }, "shopId": { "type": "string" }, "shopName": { "type": "string" } }, "required": [ "total", "date", "shopId", "shopName" ], "additionalProperties": false }, "highest": { "nullable": true, "type": "object", "properties": { "total": { "$ref": "#/components/schemas/Money" }, "date": { "type": "string" }, "shopId": { "type": "string" }, "shopName": { "type": "string" } }, "required": [ "total", "date", "shopId", "shopName" ], "additionalProperties": false }, "average": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "since": { "nullable": true, "type": "string" }, "dayCount": { "type": "integer" } }, "required": [ "current", "lowest", "highest", "average", "since", "dayCount" ], "additionalProperties": false }, "excludedShopTypes": { "type": "array", "items": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] } } }, "required": [ "product", "country", "locale", "currency", "days", "from", "to", "series", "best", "summary", "excludedShopTypes" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/specs": { "put": { "tags": [ "Products" ], "summary": "Import attributes of a product", "description": "Writes attributes (datasheet values) for a product in your account, for example from a manufacturer database. Values are checked as when maintained in the dashboard (field of the product type, type, option, unit). Choice fields also accept the label or common spellings, e.g. `wi-fi` for Wi-Fi.\n\nThe import only fills empty attributes and updates values that came from the same `source`. It never overwrites values maintained by hand or taken from datasheet extraction or enrichment; those may in turn replace imported values at any time. Repeating a call with the same data changes nothing. Titles, prices, images and identifiers are not part of the import.\n\nThe response reports per attribute: `applied` (written), `unchanged` (already stored), `skipped_existing` (a different value exists, not overwritten) or `invalid` (with a reason). If the product is unknown, the route answers with status 404.\n\nOnly with an API client that has the `products:write` permission. With a site key the route answers with status 403.", "operationId": "putProductSpecs", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:write" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Product identifier: affilinode ID or `asin:`, `gtin:`, `mpn:/`.", "example": "mpn:beispielmarke/BM-100" }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" }, { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 100 } }, { "type": "object", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 40 } ] } } ] }, "description": "Attributes as an object `{ \"fieldKey\": value }` (at most 60). The keys are listed in the data of the product type (`getCategory`). Value by field: text, number (or `{ \"value\": 6.1, \"unit\": \"in\" }`), `true`/`false`, option value, list for multiple choice." }, "source": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,39}$", "description": "Name of your source, e.g. `csa-dcl-import` (2 to 40 characters: a–z, 0–9, dot, hyphen, underscore). A later import only updates values from the same source." }, "sourceNote": { "type": "string", "maxLength": 200, "description": "Note on where the values come from, e.g. “CSA DCL, as of 2026-10-27” (at most 200 characters)." }, "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of the data as `YYYY-MM-DD`; replaces the note if that is missing." } }, "required": [ "values", "source" ] }, "example": { "values": { "radio_protocols": [ "thread", "wi-fi" ], "matter_version": "1.4", "matter_device_type": 266, "matter_certificate": "CSA00000AAA00000-24", "matter_certified_since": "2024-03-15", "matter_firmware": "1.2.3" }, "source": "csa-dcl-import", "sourceNote": "CSA DCL, Stand 2026-10-27" } } }, "description": "The attributes and where they come from." }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identifier": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "applied", "unchanged", "skipped_existing", "invalid", "not_found" ] }, "reason": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "status": { "type": "string", "enum": [ "applied", "unchanged", "skipped_existing", "invalid" ] }, "reason": { "type": "string" } }, "required": [ "field", "status" ], "additionalProperties": false } } }, "required": [ "index", "productId", "identifier", "status", "fields" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "items": { "type": "object", "properties": { "applied": { "type": "integer" }, "unchanged": { "type": "integer" }, "skipped_existing": { "type": "integer" }, "invalid": { "type": "integer" }, "not_found": { "type": "integer" } }, "required": [ "applied", "unchanged", "skipped_existing", "invalid", "not_found" ], "additionalProperties": false }, "fields": { "type": "object", "properties": { "applied": { "type": "integer" }, "unchanged": { "type": "integer" }, "skipped_existing": { "type": "integer" }, "invalid": { "type": "integer" } }, "required": [ "applied", "unchanged", "skipped_existing", "invalid" ], "additionalProperties": false } }, "required": [ "items", "fields" ], "additionalProperties": false } }, "required": [ "results", "summary" ], "additionalProperties": false }, "example": { "results": [ { "index": 0, "productId": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "identifier": "mpn:beispielmarke/BM-100", "status": "applied", "fields": [ { "field": "radio_protocols", "status": "applied" }, { "field": "matter_version", "status": "applied" }, { "field": "matter_device_type", "status": "applied" }, { "field": "matter_certificate", "status": "unchanged" }, { "field": "matter_certified_since", "status": "skipped_existing", "reason": "Wert ist von Hand gepflegt und gesperrt" }, { "field": "matter_firmware", "status": "applied" } ] } ], "summary": { "items": { "applied": 1, "unchanged": 0, "skipped_existing": 0, "invalid": 0, "not_found": 0 }, "fields": { "applied": 4, "unchanged": 1, "skipped_existing": 1, "invalid": 0 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/specs/batch": { "post": { "tags": [ "Products" ], "summary": "Import attributes of several products", "description": "Like `putProductSpecs`, but for up to 100 products in one call. Each entry names its product with `productId` or `identifier` (e.g. `mpn:ikea/E2201`). The response contains one result per entry in the same order (`applied`, `unchanged`, `skipped_existing`, `invalid` or `not_found`, with a reason) and totals over all entries. A faulty entry does not stop the others. The call is safe to repeat.\n\nOnly with an API client that has the `products:write` permission. With a site key the route answers with status 403.", "operationId": "importProductSpecs", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:write" ], "parameters": [ { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "affilinode ID of the product (alternatively `identifier`)." }, "identifier": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$", "description": "Product identifier, e.g. `mpn:ikea/E2201` or `gtin:…` (alternatively `productId`)." }, "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" }, { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 100 } }, { "type": "object", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 40 } ] } } ] }, "description": "Attributes as an object `{ \"fieldKey\": value }` (at most 60), as for `putProductSpecs`." }, "source": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,39}$", "description": "Name of your source, e.g. `csa-dcl-import`." }, "sourceNote": { "type": "string", "maxLength": 200, "description": "Note on the origin, e.g. “CSA DCL, as of 2026-10-27”." }, "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of the data as `YYYY-MM-DD`." } }, "required": [ "values", "source" ] }, "description": "Entries, one per product." } }, "required": [ "items" ] }, "example": { "items": [ { "identifier": "mpn:beispielmarke/BM-100", "values": { "matter_version": "1.4", "matter_device_type": 266 }, "source": "csa-dcl-import", "sourceNote": "CSA DCL, Stand 2026-10-27" }, { "productId": "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60", "values": { "matter_version": "1.2" }, "source": "csa-dcl-import", "asOf": "2026-10-27" } ] } } }, "description": "The entries, at most 100." }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identifier": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "applied", "unchanged", "skipped_existing", "invalid", "not_found" ] }, "reason": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "status": { "type": "string", "enum": [ "applied", "unchanged", "skipped_existing", "invalid" ] }, "reason": { "type": "string" } }, "required": [ "field", "status" ], "additionalProperties": false } } }, "required": [ "index", "productId", "identifier", "status", "fields" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "items": { "type": "object", "properties": { "applied": { "type": "integer" }, "unchanged": { "type": "integer" }, "skipped_existing": { "type": "integer" }, "invalid": { "type": "integer" }, "not_found": { "type": "integer" } }, "required": [ "applied", "unchanged", "skipped_existing", "invalid", "not_found" ], "additionalProperties": false }, "fields": { "type": "object", "properties": { "applied": { "type": "integer" }, "unchanged": { "type": "integer" }, "skipped_existing": { "type": "integer" }, "invalid": { "type": "integer" } }, "required": [ "applied", "unchanged", "skipped_existing", "invalid" ], "additionalProperties": false } }, "required": [ "items", "fields" ], "additionalProperties": false } }, "required": [ "results", "summary" ], "additionalProperties": false }, "example": { "results": [ { "index": 0, "productId": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "identifier": "mpn:beispielmarke/BM-100", "status": "applied", "fields": [ { "field": "matter_version", "status": "applied" }, { "field": "matter_device_type", "status": "applied" } ] }, { "index": 1, "productId": null, "identifier": null, "status": "not_found", "reason": "Produkt nicht gefunden (nur Produkte des eigenen Kontos)", "fields": [] } ], "summary": { "items": { "applied": 1, "unchanged": 0, "skipped_existing": 0, "invalid": 0, "not_found": 1 }, "fields": { "applied": 2, "unchanged": 0, "skipped_existing": 0, "invalid": 0 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compare": { "get": { "tags": [ "Comparisons" ], "summary": "Compare products", "description": "Puts several products side by side: the products with their offers and a table of attributes (`rows`) with best values and differences. `comparisonText` contains a ready-made comparison text where available.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "compareProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "ids", "required": true, "description": "Product identifiers, comma-separated (at most 50): the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`. Duplicates are merged.", "example": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42,9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60" }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "With `true` the successor or replacement (field `replacement`) appears instead of a product that is no longer available." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies.", "example": "DE" }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "resolved": { "type": "object", "additionalProperties": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "best": { "type": "array", "items": { "type": "integer" } }, "differs": { "type": "boolean" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] } }, "required": [ "group", "key", "label", "values", "best", "differs", "compare", "importance" ], "additionalProperties": false } }, "comparisonText": { "default": null, "nullable": true, "type": "string" } }, "required": [ "products", "resolved", "missing", "rows", "comparisonText" ], "additionalProperties": false }, "example": { "products": [ { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "detailedTitle": null, "brand": "Nova", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null }, { "id": "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60", "title": "Lumen S3 128 GB blau", "detailedTitle": null, "brand": "Lumen", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "349.00", "currency": "EUR", "formatted": "349,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "349.00", "currency": "EUR", "formatted": "349,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null } ], "resolved": { "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60": "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60" }, "missing": [], "rows": [ { "group": "Display", "key": "display_size", "label": "Bildschirmdiagonale", "values": [ "6,6 Zoll", "6,3 Zoll" ], "best": [ 0 ], "differs": true, "compare": "higher", "importance": "key" } ], "comparisonText": null } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compare/data": { "get": { "tags": [ "Comparisons" ], "summary": "Comparison data (without affiliate links)", "description": "Returns the attribute data for comparing 2 to 10 products of the same product type, without offers and affiliate links. For pages that build the presentation themselves.\n\nPermission for API clients: `catalog:read`. Site keys may always use this route.", "operationId": "getComparisonData", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "ids", "required": true, "description": "Product identifiers, comma-separated (2 to 10): the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "values": { "type": "array", "items": { "nullable": true, "type": "object", "properties": { "display": { "type": "string" }, "raw": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ] }, "source": { "type": "string" }, "sourceUrl": { "nullable": true, "type": "string" }, "confidence": { "nullable": true, "type": "number" }, "locked": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "display", "raw", "source", "sourceUrl", "confidence", "locked", "updatedAt" ], "additionalProperties": false } }, "best": { "type": "array", "items": { "type": "integer" } }, "differs": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "integer" } } }, "required": [ "group", "key", "label", "type", "unit", "unitSymbol", "compare", "importance", "values", "best", "differs", "missing" ], "additionalProperties": false } }, "facts": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "fieldKey": { "type": "string" }, "label": { "type": "string" }, "rank": { "type": "integer" }, "of": { "type": "integer" }, "percentile": { "type": "integer" }, "kind": { "type": "string", "enum": [ "best_in_category", "top_10", "typical", "bottom_10" ] } }, "required": [ "productId", "fieldKey", "label", "rank", "of", "percentile", "kind" ], "additionalProperties": false } } }, "required": [ "productType", "products", "rows", "facts" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/versus": { "get": { "tags": [ "Comparisons" ], "summary": "A versus B", "description": "Compares two or three products head to head: differences by area, overall verdict, who each product suits and frequently asked questions. Includes the same data as the comparison.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getVersus", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "ids", "required": true, "description": "Two to three product identifiers, comma-separated." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "With `true` the successor or replacement (field `replacement`) appears instead of a product that is no longer available." }, { "schema": { "default": 6, "type": "integer", "minimum": 0, "maximum": 10 }, "in": "query", "name": "faq", "required": false, "description": "Number of frequently asked questions (0 to 10). Default: 6." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "amazonPrices", "required": false, "description": "With `true` the comparison may use Amazon prices in its statements. Default: no." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "resolved": { "type": "object", "additionalProperties": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "best": { "type": "array", "items": { "type": "integer" } }, "differs": { "type": "boolean" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] } }, "required": [ "group", "key", "label", "values", "best", "differs", "compare", "importance" ], "additionalProperties": false } }, "comparisonText": { "default": null, "nullable": true, "type": "string" }, "versus": { "type": "object", "properties": { "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" } }, "required": [ "key", "label", "labelPlural" ], "additionalProperties": false }, "title": { "type": "string" }, "areas": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string", "enum": [ "display", "chip", "storage", "camera", "battery", "power", "wireless", "sound", "size", "shield", "climate", "light", "spec" ] }, "winner": { "nullable": true, "type": "integer" }, "scores": { "type": "array", "items": { "type": "number" } }, "summary": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "winners": { "type": "array", "items": { "type": "integer" } }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "text": { "nullable": true, "type": "string" } }, "required": [ "key", "label", "values", "winners", "compare", "importance", "text" ], "additionalProperties": false } } }, "required": [ "key", "label", "icon", "winner", "scores", "summary", "fields" ], "additionalProperties": false } }, "differences": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "winners": { "type": "array", "items": { "type": "integer" } }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "text": { "nullable": true, "type": "string" } }, "required": [ "key", "label", "values", "winners", "compare", "importance", "text" ], "additionalProperties": false } }, "overall": { "type": "object", "properties": { "winner": { "nullable": true, "type": "integer" }, "wins": { "type": "array", "items": { "type": "integer" } }, "summary": { "type": "string" } }, "required": [ "winner", "wins", "summary" ], "additionalProperties": false }, "buyers": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "title": { "type": "string" }, "areas": { "type": "array", "items": { "type": "string" } }, "points": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" } }, "required": [ "productId", "title", "areas", "points", "text" ], "additionalProperties": false } }, "faq": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "key", "question", "answer" ], "additionalProperties": false } }, "basis": { "type": "string" }, "pricesOmitted": { "type": "boolean" } }, "required": [ "productType", "title", "areas", "differences", "overall", "buyers", "faq", "basis", "pricesOmitted" ], "additionalProperties": false } }, "required": [ "products", "resolved", "missing", "rows", "comparisonText", "versus" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/versus/suggestions": { "get": { "tags": [ "Comparisons" ], "summary": "Suggestions for comparisons", "description": "Suggests product pairs that work well side by side – for one product or for a product type.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getVersusSuggestions", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "query", "name": "product", "required": false, "description": "Identifier of the product to suggest opponents for." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Key of a product type, for example `smartphone`. Returns pairs from this product type." }, { "schema": { "default": 6, "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of suggestions (1 to 20). Default: 6." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (default) considers all products of your account, `site` only the products your website already shows. `site` only works with a site key (otherwise status 403)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "required": [ "id", "title", "brand", "productType" ], "additionalProperties": false } }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "same_type", "similar_price", "similar_specs", "same_series", "same_brand", "compared_together", "popular", "successor", "alternative" ] } } }, "required": [ "key", "products", "score", "reasons" ], "additionalProperties": false } } }, "required": [ "suggestions" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compare-tables/{id}": { "get": { "tags": [ "Comparisons" ], "summary": "Saved comparison table", "description": "Returns a comparison table created in the dashboard with its products, rows and highlights. Tables built from the product search update themselves.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getCompareTable", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Identifier of the comparison table (from the dashboard)." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "With `true` the successor or replacement (field `replacement`) appears instead of a product that is no longer available." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "table": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "updatedAt": { "type": "string" }, "onlyDifferences": { "type": "boolean" }, "highlight": { "nullable": true, "type": "object", "properties": { "productId": { "type": "string" }, "badge": { "type": "string" } }, "required": [ "productId", "badge" ], "additionalProperties": false } }, "required": [ "id", "name", "updatedAt", "onlyDifferences", "highlight" ], "additionalProperties": false }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "rows": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "standard" ] }, "key": { "type": "string", "enum": [ "image", "title", "rating", "review", "price", "button", "pros", "cons", "highlights" ] }, "label": { "nullable": true, "type": "string" } }, "required": [ "type", "key", "label" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "field" ] }, "key": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "best": { "type": "array", "items": { "type": "integer" } }, "differs": { "type": "boolean" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] } }, "required": [ "type", "key", "label", "group", "values", "best", "differs", "compare", "importance" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "yesno" ] }, "values": { "type": "array", "items": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "boolean" } ] } }, "differs": { "type": "boolean" } }, "required": [ "type", "key", "label", "kind", "values", "differs" ], "additionalProperties": false } ] } }, "missing": { "type": "array", "items": { "type": "string" } }, "comparisonText": { "default": null, "nullable": true, "type": "string" } }, "required": [ "table", "products", "rows", "missing", "comparisonText" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/lists": { "get": { "tags": [ "Lists" ], "summary": "List product lists", "description": "Returns the product lists of your account with type, title, number of entries and last change.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getLists", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "q", "required": false, "description": "Search term in the list title." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "manual", "dynamic", "shop" ] }, "title": { "nullable": true, "type": "string" }, "itemCount": { "type": "integer" }, "updatedAt": { "type": "string" } }, "required": [ "id", "type", "title", "itemCount", "updatedAt" ], "additionalProperties": false } } }, "required": [ "lists" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/lists/amazon": { "get": { "tags": [ "Lists" ], "summary": "Amazon bestsellers for a keyword", "description": "Returns an automatic list of bestsellers or new releases for a keyword. The products are created on the first request; `list.source.status` shows whether the list is still being built (`building`).\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getAmazonList", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 2, "maxLength": 100 }, "in": "query", "name": "keyword", "required": true, "description": "Keyword to search for." }, { "schema": { "default": "bestseller", "type": "string", "enum": [ "bestseller", "new" ] }, "in": "query", "name": "sort", "required": false, "description": "`bestseller` (default) or `new` (new releases)." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "limit", "required": false, "description": "Number of products (1 to 10). Default: 10." }, { "schema": { "type": "string", "pattern": "^\\d{1,20}$" }, "in": "query", "name": "node", "required": false, "description": "Optional: number of the Amazon category (browse node) to narrow the list." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "With `true` the successor or replacement (field `replacement`) appears instead of a product that is no longer available." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "manual", "dynamic", "shop" ] }, "title": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "updatedAt": { "type": "string" }, "source": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "amazon_search" ] }, "keyword": { "type": "string" }, "sort": { "type": "string", "enum": [ "bestseller", "new" ] }, "status": { "type": "string", "enum": [ "building", "ready", "error" ] }, "refreshedAt": { "nullable": true, "type": "string" } }, "required": [ "type", "keyword", "sort", "status", "refreshedAt" ], "additionalProperties": false } }, "required": [ "id", "type", "title", "description", "updatedAt" ], "additionalProperties": false }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListItem" } }, "total": { "type": "integer" } }, "required": [ "list", "items", "total" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/lists/{id}": { "get": { "tags": [ "Lists" ], "summary": "Get a list", "description": "Returns a product list with its entries in the set order – each with product, offers, editorial note and badge (for example “Test winner”).\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getList", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Identifier of the list (from the dashboard or from `getLists`).", "example": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8" }, { "schema": { "default": 24, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Number of entries per page (1 to 100). Default: 24.", "example": 10 }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 10000 }, "in": "query", "name": "offset", "required": false, "description": "Number of entries to skip (for the next page). Default: 0." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "With `true` the successor or replacement (field `replacement`) appears instead of a product that is no longer available." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "manual", "dynamic", "shop" ] }, "title": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "updatedAt": { "type": "string" }, "source": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "amazon_search" ] }, "keyword": { "type": "string" }, "sort": { "type": "string", "enum": [ "bestseller", "new" ] }, "status": { "type": "string", "enum": [ "building", "ready", "error" ] }, "refreshedAt": { "nullable": true, "type": "string" } }, "required": [ "type", "keyword", "sort", "status", "refreshedAt" ], "additionalProperties": false } }, "required": [ "id", "type", "title", "description", "updatedAt" ], "additionalProperties": false }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListItem" } }, "total": { "type": "integer" } }, "required": [ "list", "items", "total" ], "additionalProperties": false }, "example": { "list": { "id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8", "type": "manual", "title": "Die besten Smartphones bis 400 Euro", "description": null, "updatedAt": "2026-10-18T12:00:00.000Z" }, "items": [ { "position": 1, "badge": "Testsieger", "note": "Bester Allrounder", "product": { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "detailedTitle": null, "brand": "Nova", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null } }, { "position": 2, "badge": null, "note": null, "product": { "id": "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60", "title": "Lumen S3 128 GB blau", "detailedTitle": null, "brand": "Lumen", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "349.00", "currency": "EUR", "formatted": "349,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "349.00", "currency": "EUR", "formatted": "349,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null } } ], "total": 2 } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/deals": { "get": { "tags": [ "Deals and coupons" ], "summary": "Current price drops", "description": "Returns products whose best price has demonstrably dropped, with the drop in percent compared with the lowest price of the 30 days before and the day of the drop. Available depending on your plan.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getDeals", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 400, "pattern": "^[a-z0-9_,]*$" }, "in": "query", "name": "type", "required": false, "description": "Only products of these product types, keys comma-separated, for example `smartphone,tablet`.", "example": "smartphone" }, { "schema": { "type": "integer", "minimum": 3, "maximum": 80 }, "in": "query", "name": "minDrop", "required": false, "description": "Minimum drop in percent (3 to 80).", "example": 10 }, { "schema": { "type": "string", "maxLength": 400, "pattern": "^[\\p{L}\\p{N}_ .+/()\\-,;=]*$" }, "in": "query", "name": "filter", "required": false, "description": "Feature filter `field=value1,value2;field2=value`: several values of one feature separated by commas (OR), several features by semicolons (AND), at most 5 features and 20 values per feature. Products without the feature are not returned. Unknown features or values return 400." }, { "schema": { "type": "integer", "minimum": 7, "maximum": 365 }, "in": "query", "name": "best", "required": false, "description": "Only deals whose current best price is the lowest of the last N days (7 to 365). Applies only when the price record covers the whole period." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "minOffers", "required": false, "description": "Minimum number of shops with a current, available price for new items (1 to 10)." }, { "schema": { "default": 12, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of entries (1 to 50). Default: 12.", "example": 12 }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "badge": { "nullable": true, "type": "string" }, "note": { "nullable": true, "type": "string" }, "product": { "$ref": "#/components/schemas/ProductWithReplacement" }, "deal": { "type": "object", "properties": { "dropPercent": { "type": "integer" }, "since": { "nullable": true, "type": "string" }, "lowestDays": { "default": null, "nullable": true, "type": "integer" }, "belowAverage": { "default": null, "nullable": true, "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "shops": { "type": "integer" } }, "required": [ "amount", "shops" ], "additionalProperties": false }, "comparableShops": { "default": 0, "type": "integer" } }, "required": [ "dropPercent", "since", "lowestDays", "belowAverage", "comparableShops" ], "additionalProperties": false } }, "required": [ "position", "badge", "note", "product", "deal" ], "additionalProperties": false } }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "additionalProperties": false }, "example": { "items": [ { "position": 1, "badge": null, "note": null, "product": { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "detailedTitle": null, "brand": "Nova", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null }, "deal": { "dropPercent": 14, "since": "2026-10-17" } } ], "total": 1 } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/coupons": { "get": { "tags": [ "Deals and coupons" ], "summary": "Coupons and promotions", "description": "Returns coupon codes, discount promotions and free-shipping offers from merchants, optionally for a shop, merchant or product.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getCoupons", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "shop", "required": false, "description": "Only coupons of this shop (shop ID from the dashboard)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "merchant", "required": false, "description": "Only coupons of this merchant (name)." }, { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "query", "name": "product", "required": false, "description": "Product identifier: the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "type": "string" }, "in": "query", "name": "kind", "required": false, "description": "Only these kinds, comma-separated: `code` (coupon code), `offer` (promotion), `free_shipping` (free shipping).", "example": "code,free_shipping" }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of entries (1 to 50). Default: 10.", "example": 10 }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "shop": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "logoUrl": { "nullable": true, "type": "string" } }, "required": [ "id", "type", "name", "logoUrl" ], "additionalProperties": false }, "merchant": { "type": "object", "properties": { "id": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "kind": { "type": "string", "enum": [ "code", "offer", "free_shipping" ] }, "code": { "nullable": true, "type": "string" }, "title": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "terms": { "nullable": true, "type": "string" }, "discount": { "nullable": true, "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "enum": [ "percent", "amount" ] }, "currency": { "nullable": true, "type": "string" }, "formatted": { "type": "string" } }, "required": [ "value", "type", "currency", "formatted" ], "additionalProperties": false }, "minOrderValue": { "nullable": true, "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" }, "formatted": { "type": "string" } }, "required": [ "amount", "currency", "formatted" ], "additionalProperties": false }, "startsAt": { "nullable": true, "type": "string" }, "endsAt": { "nullable": true, "type": "string" }, "url": { "nullable": true, "type": "string" }, "exclusive": { "type": "boolean" }, "revealOpensLink": { "type": "boolean" }, "source": { "type": "string", "enum": [ "awin", "tradedoubler", "webgains", "manual", "creator" ] } }, "required": [ "id", "shop", "merchant", "kind", "code", "title", "description", "terms", "discount", "minOrderValue", "startsAt", "endsAt", "url", "exclusive", "revealOpensLink", "source" ], "additionalProperties": false } }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "additionalProperties": false }, "example": { "items": [ { "id": "a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null }, "merchant": { "id": "12345", "name": "Elektro-Markt" }, "kind": "code", "code": "HERBST10", "title": "10 % auf alle Haushaltsgeräte", "description": null, "terms": "Mindestbestellwert 50 €", "discount": { "type": "percent", "value": "10", "currency": null, "formatted": "10 %" }, "minOrderValue": { "amount": "50.00", "currency": "EUR", "formatted": "50,00 €" }, "startsAt": "2026-10-01T00:00:00.000Z", "endsAt": "2026-10-31T23:59:59.000Z", "url": "https://www.elektro-markt.example/gutschein?ref=ab12cd34", "exclusive": false, "revealOpensLink": false, "source": "awin" } ], "total": 1 } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/creator-codes/{id}/copied": { "post": { "tags": [ "Deals and coupons" ], "summary": "Report: discount code copied", "description": "Reports that a visitor copied one of your own discount codes. Only the total per day and place is counted, no individual. Unknown or expired codes are silently ignored; the response is always empty.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "reportCreatorCodeCopied", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Identifier of the discount code (from the dashboard)." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "default": "api", "type": "string", "enum": [ "embed", "plugin", "api" ], "description": "Place: `embed` (embedded box), `plugin` (WordPress) or `api` (your own application). Default: `api`." } } } } }, "description": "Where the code was copied." }, "responses": { "204": { "description": "Successful, no response data", "content": { "application/json": { "schema": { "type": "string", "nullable": true, "enum": [ null ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/search": { "get": { "tags": [ "Search" ], "summary": "Search products", "description": "Searches products by title, brand, ASIN, EAN or model number and returns compact hits with image and best price.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "searchProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "in": "query", "name": "q", "required": true, "description": "Search term or identifier.", "example": "nova x5" }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Only hits of this product type (key), for example `smartphone`." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of hits (1 to 50). Default: 20.", "example": 5 }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" } }, "total": { "type": "integer" } }, "required": [ "hits", "total" ], "additionalProperties": false }, "example": { "hits": [ { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "brand": "Nova", "productType": { "key": "smartphone", "label": "Smartphone" }, "image": { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null }, "bestPrice": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "offerCount": 2, "status": "available", "identifiers": [ { "type": "asin", "value": "B0CHX1W1XY" }, { "type": "gtin", "value": "4006381333931" } ] } ], "total": 1 } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/search": { "get": { "tags": [ "Search" ], "summary": "Product search with filters", "description": "Searches products of a product type with filters and facets (choices with hit counts) and pages through the results. Meant for category pages with a filter bar. The products come without offers and affiliate links.\n\nPass filters as `filter[]`: `filter[brand]=Bosch,Makita`, `filter[price]=50..200` (also `..100` or `150..`), `filter[availability]=available` and, for attributes of the product type, `filter[voltage]=18..`, `filter[chuck_type]=a,b` or `filter[brushless_motor]=true`. Attribute filters need the `type` parameter. At most 20 filters.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "searchProductsFaceted", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "q", "required": false, "description": "Search term." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Key of the product type, for example `smartphone`." }, { "schema": { "type": "string", "maxLength": 1000 }, "in": "query", "name": "facets", "required": false, "description": "Facets (choices with hit counts), comma-separated and in this order, at most 12, for example `brand,price,availability,field:voltage`. Without it the default facets apply." }, { "schema": { "type": "string", "pattern": "^(relevance|popular|title|updated|-?price|-?field:[a-z0-9_]{1,64})$" }, "in": "query", "name": "sort", "required": false, "description": "Sorting: `relevance` (default with a search term), `popular` (default otherwise), `title`, `updated`, `price`, `-price`, `field:` or `-field:` (number attributes only)." }, { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "page", "required": false, "description": "Page (from 1). Default: 1." }, { "schema": { "default": 12, "type": "integer", "minimum": 1, "maximum": 48 }, "in": "query", "name": "perPage", "required": false, "description": "Hits per page (1 to 48). Default: 12." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (default) considers all products of your account, `site` only the products your website already shows. `site` only works with a site key (otherwise status 403)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string" }, "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "facets": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "brand", "availability", "field" ] }, "type": { "type": "string", "enum": [ "values" ] }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "selected": { "type": "boolean" } }, "required": [ "value", "label", "count", "selected" ], "additionalProperties": false } } }, "required": [ "key", "kind", "type", "label", "values" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "price", "field" ] }, "type": { "type": "string", "enum": [ "range" ] }, "label": { "type": "string" }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" }, "count": { "type": "integer" }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "currency": { "nullable": true, "type": "string" }, "selected": { "nullable": true, "type": "object", "properties": { "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" } }, "required": [ "min", "max" ], "additionalProperties": false } }, "required": [ "key", "kind", "type", "label", "min", "max", "count", "unit", "unitSymbol", "currency", "selected" ], "additionalProperties": false } ] } } }, "required": [ "items", "total", "page", "perPage", "pages", "sort", "productType", "facets" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories": { "get": { "tags": [ "Catalog" ], "summary": "List product types", "description": "Returns all product types in the catalog (for example smartphone, cordless drill) with the number of products.\n\nPermission for API clients: `catalog:read`. Site keys may always use this route.", "operationId": "getCategories", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "links", "required": false, "description": "With `true` cross-references to related product types are included." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "parentKey": { "nullable": true, "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" }, "abstract": { "type": "boolean" }, "productCount": { "type": "integer" }, "totalProductCount": { "type": "integer" }, "link": { "type": "boolean" }, "canonicalKey": { "type": "string" }, "canonicalParentKey": { "nullable": true, "type": "string" }, "canonicalPath": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "parentKey", "label", "labelPlural", "abstract", "productCount", "totalProductCount" ], "additionalProperties": false } } }, "required": [ "categories" ], "additionalProperties": false }, "example": { "categories": [ { "key": "smartphone", "parentKey": "mobile_device", "label": "Smartphone", "labelPlural": "Smartphones", "abstract": false, "productCount": 412, "totalProductCount": 412 } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories/{type}": { "get": { "tags": [ "Catalog" ], "summary": "Product type with attributes", "description": "Returns a product type with its attributes: groups, labels, units, choices and how values are rated (higher or lower is better). The attributes are the basis for filters and comparisons.\n\nPermission for API clients: `catalog:read`. Site keys may always use this route.", "operationId": "getCategory", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "type", "required": true, "description": "Key of the product type, for example `smartphone` (from `getCategories`)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "parentKey": { "nullable": true, "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" }, "abstract": { "type": "boolean" }, "path": { "type": "array", "items": { "type": "string" } }, "googleProductCategory": { "nullable": true, "type": "object", "properties": { "id": { "type": "integer" }, "path": { "type": "string" } }, "required": [ "id", "path" ], "additionalProperties": false }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "string" }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "required": { "type": "boolean" }, "filterable": { "type": "boolean" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" }, "options": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "variantAxis": { "type": "boolean" } }, "required": [ "key", "type", "label", "group", "importance", "required", "filterable", "compare", "unit", "unitSymbol", "min", "max", "options", "variantAxis" ], "additionalProperties": false } } }, "required": [ "key", "parentKey", "label", "labelPlural", "abstract", "path", "googleProductCategory", "groups", "fields" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories/{type}/products": { "get": { "tags": [ "Catalog" ], "summary": "Products of a product type", "description": "Returns the products of a product type without offers and affiliate links, with filters, facets and continuation via `nextCursor`.\n\nFilter by attributes of the product type with `f.`: number ranges as `f.power=18..36`, options as `f.color=black,white`, yes/no as `f.wifi=true`. `getCategory` lists the available attributes.\n\nSorting: `popular` (default), `title`, `updated`, `price`, `-price` (descending), `field:` or `-field:`.\n\nPermission for API clients: `catalog:read`. Site keys may always use this route.", "operationId": "getCategoryProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "type", "required": true, "description": "Key of the product type, for example `smartphone`." }, { "schema": { "type": "string", "maxLength": 500 }, "in": "query", "name": "brand", "required": false, "description": "Only these brands, comma-separated, for example `Bosch,Makita`." }, { "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "in": "query", "name": "q", "required": false, "description": "Search term in title or brand (at least 2 characters)." }, { "schema": { "default": "popular", "type": "string", "pattern": "^(popular|title|updated|-?price|-?field:[a-z0-9_]{1,64})$" }, "in": "query", "name": "sort", "required": false, "description": "Sorting, see the description. Default: `popular`." }, { "schema": { "default": 24, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of entries in the response. The allowed values are in the schema." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false, "description": "Continuation: the `nextCursor` value from the previous response. Without it the list starts from the beginning." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } }, "total": { "type": "integer" }, "facets": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogFacet" } }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "items", "total", "facets", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/views": { "get": { "tags": [ "Catalog" ], "summary": "List views", "description": "Returns the prepared views of the catalog – fixed combinations of product type and filters, for example “cordless drills up to 18 V”.\n\nPermission for API clients: `catalog:read`. Site keys may always use this route.", "operationId": "getViews", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Only views of this product type (key)." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "views": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "productTypeKey": { "type": "string" }, "label": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "filters": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "key", "productTypeKey", "label", "description", "filters" ], "additionalProperties": false } } }, "required": [ "views" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/views/{key}/products": { "get": { "tags": [ "Catalog" ], "summary": "Products of a view", "description": "Returns the products of a view without offers and affiliate links. Additional filters apply on top of the view’s own filters.\n\nFilter by attributes of the product type with `f.`: number ranges as `f.power=18..36`, options as `f.color=black,white`, yes/no as `f.wifi=true`. `getCategory` lists the available attributes.\n\nSorting: `popular` (default), `title`, `updated`, `price`, `-price` (descending), `field:` or `-field:`.\n\nPermission for API clients: `catalog:read`. Site keys may always use this route.", "operationId": "getViewProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "key", "required": true, "description": "Key of the view (from `getViews`)." }, { "schema": { "type": "string", "maxLength": 500 }, "in": "query", "name": "brand", "required": false, "description": "Only these brands, comma-separated." }, { "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "in": "query", "name": "q", "required": false, "description": "Search term in title or brand (at least 2 characters)." }, { "schema": { "default": "popular", "type": "string", "pattern": "^(popular|title|updated|-?price|-?field:[a-z0-9_]{1,64})$" }, "in": "query", "name": "sort", "required": false, "description": "Sorting, see the description. Default: `popular`." }, { "schema": { "default": 24, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of entries in the response. The allowed values are in the schema." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false, "description": "Continuation: the `nextCursor` value from the previous response. Without it the list starts from the beginning." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } }, "total": { "type": "integer" }, "facets": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogFacet" } }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "items", "total", "facets", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/catalog/changes": { "get": { "tags": [ "Catalog" ], "summary": "Changes since a point in time", "description": "Returns the products that changed since a point in time (new, updated or removed). Use it to keep your own database up to date without reloading everything. Keep reading with `cursor` until `nextCursor` is empty.\n\nPermission for API clients: `catalog:read`. Site keys may always use this route.", "operationId": "getCatalogChanges", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "since", "required": true, "description": "Point in time as date and time in ISO 8601, for example `2026-10-01T00:00:00Z`." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Only changes of this product type (key)." }, { "schema": { "type": "string", "maxLength": 300 }, "in": "query", "name": "cursor", "required": false, "description": "Continuation: the `nextCursor` value from the previous response. Without it the list starts from the beginning." }, { "schema": { "default": 500, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of entries (1 to 1000). Default: 500." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productTypeKey": { "type": "string" }, "activityState": { "nullable": true, "type": "string" }, "status": { "nullable": true, "type": "string" }, "deleted": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "id", "productTypeKey", "activityState", "status", "deleted", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "items", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/pairs": { "get": { "tags": [ "Catalog" ], "summary": "Matching product pairs", "description": "Suggests, for a product type, pairs of products that work well side by side, with a score from 0 to 1 and the reasons.\n\nPermission for API clients: `catalog:read`. Site keys may always use this route.", "operationId": "getProductPairs", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": true, "description": "Key of the product type, for example `smartphone`." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false, "description": "Continuation: the `nextCursor` value from the previous response. Without it the list starts from the beginning." }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Number of starting products per page (1 to 100). Default: 50." }, { "schema": { "default": 3, "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "perProduct", "required": false, "description": "Suggestions per starting product (1 to 10). Default: 3." }, { "schema": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "in": "query", "name": "minScore", "required": false, "description": "Minimum score of a pair from 0 to 1. Default: 0.5." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "pairs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "productIds": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "string" } ] }, "minItems": 2, "maxItems": 2 }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "productIds", "score", "reasons" ], "additionalProperties": false } }, "productCount": { "type": "integer" }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "pairs", "productCount", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compatibility/systems": { "get": { "tags": [ "Catalog" ], "summary": "Systems for the compatibility check", "description": "Returns the systems for which compatibility information exists (for example battery platforms or smart-home standards), with the number of matching products.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getCompatibilitySystems", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Only systems that apply to this product type (key)." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "kind", "required": false, "description": "Only systems of these kinds, comma-separated: `hub`, `ecosystem`, `radio`, `battery`, `socket` or `lens_mount`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "systems": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "hub", "ecosystem", "radio", "battery", "socket", "lens_mount" ] }, "kindLabel": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "key", "kind", "kindLabel", "label", "count" ], "additionalProperties": false } } }, "required": [ "systems" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compatibility": { "get": { "tags": [ "Catalog" ], "summary": "Products that fit a system", "description": "Answers “Does this fit my …?”: returns the products (without affiliate links) that are compatible with a system, each with the evidence – or checks a single product against the system.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getCompatibleProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 80 }, "in": "query", "name": "system", "required": true, "description": "Key of the system in the form `:`, for example `hub:zha` or `battery:makitalxt18v` (from `getCompatibilitySystems`)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "product", "required": false, "description": "Optional: identifier of a product to check against the system." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Only products of this product type (key)." }, { "schema": { "default": "popular", "type": "string", "enum": [ "popular", "price", "-price", "title" ] }, "in": "query", "name": "sort", "required": false, "description": "Sorting: `popular` (default), `price`, `-price` or `title`." }, { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "page", "required": false, "description": "Page (from 1). Default: 1." }, { "schema": { "default": 12, "type": "integer", "minimum": 1, "maximum": 48 }, "in": "query", "name": "perPage", "required": false, "description": "Hits per page (1 to 48). Default: 12." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "list" ] }, "system": { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "hub", "ecosystem", "radio", "battery", "socket", "lens_mount" ] }, "kindLabel": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "kind", "kindLabel", "label" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "model": { "nullable": true, "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "activityState": { "type": "string", "enum": [ "catalog", "active", "paused" ] }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ] }, "image": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "keySpecs": { "type": "array", "items": { "$ref": "#/components/schemas/SpecItem" } }, "specCount": { "type": "integer" }, "completeness": { "$ref": "#/components/schemas/SpecCompleteness" }, "bestPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "offerCount": { "type": "integer" }, "popularity": { "type": "object", "properties": { "clicks30d": { "type": "integer" }, "impressions30d": { "type": "integer" }, "orders30d": { "type": "integer" }, "sites": { "type": "integer" }, "lastRequestedAt": { "nullable": true, "type": "string" } }, "required": [ "clicks30d", "impressions30d", "orders30d", "sites", "lastRequestedAt" ], "additionalProperties": false }, "updatedAt": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceLabel": { "type": "string" }, "sourceUrl": { "nullable": true, "type": "string" }, "basis": { "type": "string", "enum": [ "spec", "listing" ] }, "field": { "nullable": true, "type": "string" } }, "required": [ "source", "sourceLabel", "sourceUrl", "basis", "field" ], "additionalProperties": false } } }, "required": [ "id", "title", "brand", "model", "productType", "activityState", "status", "image", "keySpecs", "specCount", "completeness", "bestPrice", "offerCount", "popularity", "updatedAt", "evidence" ], "additionalProperties": false } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string" }, "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "required": [ "mode", "system", "items", "total", "page", "perPage", "pages", "sort", "productType" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "check" ] }, "system": { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "hub", "ecosystem", "radio", "battery", "socket", "lens_mount" ] }, "kindLabel": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "kind", "kindLabel", "label" ], "additionalProperties": false }, "product": { "$ref": "#/components/schemas/CatalogProduct" }, "verdict": { "type": "string", "enum": [ "yes", "no", "unknown" ] }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceLabel": { "type": "string" }, "sourceUrl": { "nullable": true, "type": "string" }, "basis": { "type": "string", "enum": [ "spec", "listing" ] }, "field": { "nullable": true, "type": "string" } }, "required": [ "source", "sourceLabel", "sourceUrl", "basis", "field" ], "additionalProperties": false } } }, "required": [ "mode", "system", "product", "verdict", "reason", "evidence" ], "additionalProperties": false } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/alternatives": { "get": { "tags": [ "Guidance and recommendations" ], "summary": "Alternatives to a product", "description": "Returns alternatives to a product: cheaper, better equipped or successors – each with the reason. `settings` shows the thresholds used for the search.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getProductAlternatives", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Product identifier: the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "kinds", "required": false, "description": "Wanted kinds, comma-separated: `cheaper`, `better`, `successor`. Default: all." }, { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 6 }, "in": "query", "name": "limit", "required": false, "description": "Number of suggestions per kind (1 to 6). Default: 1." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 90 }, "in": "query", "name": "cheaperBy", "required": false, "description": "Minimum saving in percent for “cheaper” (1 to 90). Default: 10." }, { "schema": { "default": 20, "type": "integer", "minimum": 0, "maximum": 200 }, "in": "query", "name": "maxPremium", "required": false, "description": "Maximum surcharge in percent for “better equipped” (0 to 200). Default: 20." }, { "schema": { "default": 60, "type": "integer", "minimum": 10, "maximum": 100 }, "in": "query", "name": "minSimilarity", "required": false, "description": "Minimum similarity in percent (10 to 100). Default: 60." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (default) considers all products of your account, `site` only the products your website already shows. `site` only works with a site key (otherwise status 403)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cheaper", "better", "successor" ] }, "label": { "type": "string" }, "neutralLabel": { "type": "string" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "similarity": { "nullable": true, "type": "integer" }, "reasons": { "type": "array", "items": { "type": "string" } }, "tradeOffs": { "type": "array", "items": { "type": "string" } }, "amazonPrice": { "type": "boolean" }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "kind", "label", "neutralLabel", "productId", "similarity", "reasons", "tradeOffs", "amazonPrice", "product" ], "additionalProperties": false } }, "settings": { "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "string", "enum": [ "cheaper", "better", "successor" ] } }, "limit": { "type": "integer" }, "cheaperBy": { "type": "integer" }, "maxPremium": { "type": "integer" }, "minSimilarity": { "type": "integer" } }, "required": [ "kinds", "limit", "cheaperBy", "maxPremium", "minSimilarity" ], "additionalProperties": false } }, "required": [ "productId", "productType", "items", "settings" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/complements": { "get": { "tags": [ "Guidance and recommendations" ], "summary": "Goes well with", "description": "Returns other devices people often buy in addition to a product (for example a door sensor next to a water sensor of the same brand) – neither accessory nor alternative. Only confirmed relations are returned.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getProductComplements", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Product identifier: the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "default": 4, "type": "integer", "minimum": 1, "maximum": 6 }, "in": "query", "name": "limit", "required": false, "description": "Number of products (1 to 6). Default: 4." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (default) considers all products of your account, `site` only the products your website already shows. `site` only works with a site key (otherwise status 403)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reason": { "nullable": true, "type": "string" }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "productId", "reason", "product" ], "additionalProperties": false } } }, "required": [ "productId", "items" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/similar": { "get": { "tags": [ "Guidance and recommendations" ], "summary": "Similar products", "description": "Returns products of the same product type with attributes similar to the given product, without affiliate links.\n\nPermission for API clients: `catalog:read`. Site keys may always use this route.", "operationId": "getSimilarProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Product identifier: the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of products (1 to 50). Default: 10." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/CatalogProduct" }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "product", "score", "reasons" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/highlights": { "get": { "tags": [ "Guidance and recommendations" ], "summary": "Strengths of a product “at a glance”", "description": "Returns the most important key figures of a product, ranked within its product type: how does it compare with the others (for example “better than 80 % of smartphones”)?\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getProductHighlights", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Product identifier: the affilinode ID or `asin:…`, `gtin:…`, `mpn:brand/model`." }, { "schema": { "default": 6, "type": "integer", "minimum": 1, "maximum": 12 }, "in": "query", "name": "count", "required": false, "description": "Number of key figures (1 to 12). Default: 6." }, { "schema": { "type": "string", "maxLength": 600 }, "in": "query", "name": "fields", "required": false, "description": "Only these attributes, keys comma-separated. Without it affilinode picks the most important ones." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" } }, "required": [ "key", "label", "labelPlural" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "nullable": true, "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "icon": { "type": "string", "enum": [ "display", "chip", "storage", "camera", "battery", "power", "wireless", "sound", "size", "shield", "climate", "light", "spec" ] }, "value": { "type": "string" }, "raw": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ] }, "unit": { "nullable": true, "type": "string" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "sample": { "nullable": true, "type": "integer" }, "rating": { "nullable": true, "type": "object", "properties": { "percentile": { "type": "integer" }, "betterThan": { "type": "integer" }, "sameAs": { "type": "integer" }, "worseThan": { "type": "integer" }, "tier": { "type": "integer" }, "summary": { "type": "string" }, "text": { "type": "string" } }, "required": [ "percentile", "betterThan", "sameAs", "worseThan", "tier", "summary", "text" ], "additionalProperties": false } }, "required": [ "key", "label", "group", "icon", "value", "raw", "unit", "compare", "importance", "sample", "rating" ], "additionalProperties": false } }, "minSample": { "type": "integer" } }, "required": [ "productId", "productType", "items", "minSample" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories/{type}/top": { "get": { "tags": [ "Guidance and recommendations" ], "summary": "Best products of a product type", "description": "Returns the best products of a product type by rating, value for money or an attribute – with title and badge for a top list.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getCategoryTop", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "type", "required": true, "description": "Key of the product type, for example `smartphone`." }, { "schema": { "default": "rating", "type": "string", "pattern": "^(rating|value|value:[a-z0-9_]{1,64}|field:[a-z0-9_]{1,64})$" }, "in": "query", "name": "by", "required": false, "description": "Ranking: `rating` (test score, default), `value` (value for money), `value:` (attribute value per euro) or `field:` (value of an attribute)." }, { "schema": { "default": 3, "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "limit", "required": false, "description": "Number of products (1 to 10). Default: 3." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (default) considers all products of your account, `site` only the products your website already shows. `site` only works with a site key (otherwise status 403)." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] }, "in": "query", "name": "available", "required": false, "description": "With `false` products without a current price are included too (not with `by=value`)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" } }, "required": [ "key", "label", "labelPlural" ], "additionalProperties": false }, "by": { "type": "string", "enum": [ "rating", "value", "field" ] }, "field": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "direction": { "type": "string", "enum": [ "higher", "lower" ] } }, "required": [ "key", "label", "unit", "unitSymbol", "direction" ], "additionalProperties": false }, "coreFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string", "enum": [ "higher", "lower" ] } }, "required": [ "key", "label", "direction" ], "additionalProperties": false } }, "title": { "type": "string" }, "badge": { "type": "string" }, "currency": { "nullable": true, "type": "string" }, "total": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "value": { "type": "number" }, "valueText": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "badge": { "nullable": true, "type": "string" }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "rank", "productId", "value", "valueText", "reasons", "badge", "product" ], "additionalProperties": false } }, "generatedAt": { "type": "string" } }, "required": [ "productType", "by", "field", "coreFields", "title", "badge", "currency", "total", "items", "generatedAt" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories/{type}/scatter": { "get": { "tags": [ "Guidance and recommendations" ], "summary": "Value-for-money chart", "description": "Returns the data for a chart that plots price against an attribute: one point per product, plus the axes and value ranges.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getCategoryScatter", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "type", "required": true, "description": "Key of the product type, for example `smartphone`." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "field", "required": true, "description": "Key of the attribute for the vertical axis (from `getCategory`)." }, { "schema": { "default": 60, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Number of points (1 to 100). Default: 60." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (default) considers all products of your account, `site` only the products your website already shows. `site` only works with a site key (otherwise status 403)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "highlight", "required": false, "description": "Identifier of a product to highlight in the chart." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" } }, "required": [ "key", "label", "labelPlural" ], "additionalProperties": false }, "x": { "type": "object", "properties": { "label": { "type": "string" }, "currency": { "nullable": true, "type": "string" }, "direction": { "type": "string", "enum": [ "lower" ] }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" } }, "required": [ "label", "currency", "direction", "min", "max" ], "additionalProperties": false }, "y": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "direction": { "nullable": true, "type": "string", "enum": [ "higher", "lower" ] }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" } }, "required": [ "key", "label", "unit", "unitSymbol", "direction", "min", "max" ], "additionalProperties": false }, "title": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "price": { "type": "number" }, "priceText": { "type": "string" }, "value": { "type": "number" }, "valueText": { "type": "string" }, "image": { "nullable": true, "type": "object", "properties": { "url": { "type": "string" }, "width": { "nullable": true, "type": "integer" }, "height": { "nullable": true, "type": "integer" } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "shop": { "nullable": true, "type": "string" }, "highlight": { "type": "boolean" } }, "required": [ "productId", "title", "price", "priceText", "value", "valueText", "image", "shop", "highlight" ], "additionalProperties": false } }, "total": { "type": "integer" }, "outliers": { "type": "integer" }, "highlight": { "nullable": true, "type": "object", "properties": { "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "shown", "not_found", "other_type", "no_price", "no_value" ] } }, "required": [ "productId", "state" ], "additionalProperties": false }, "amazonPrice": { "type": "boolean" }, "generatedAt": { "type": "string" } }, "required": [ "productType", "x", "y", "title", "points", "total", "outliers", "highlight", "amazonPrice", "generatedAt" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/advisors/{id}": { "get": { "tags": [ "Guidance and recommendations" ], "summary": "Get a product advisor", "description": "Returns a product advisor (buying-guide quiz) created in the dashboard, with introduction, questions and answer options.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getAdvisor", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Identifier of the product advisor (from the dashboard)." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "locale": { "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "intro": { "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "single", "multi", "yesno", "range" ] }, "title": { "type": "string" }, "help": { "type": "string" }, "showIf": { "nullable": true, "type": "object", "properties": { "question": { "type": "string", "pattern": "^[a-z0-9]{1,16}$" }, "answers": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]{1,16}$" } } }, "required": [ "question", "answers" ], "additionalProperties": false }, "any": { "nullable": true, "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false } }, "range": { "nullable": true, "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "step": { "type": "number" }, "default": { "type": "number" }, "unitSymbol": { "nullable": true, "type": "string" }, "currency": { "nullable": true, "type": "string" }, "op": { "type": "string", "enum": [ "max", "min" ] } }, "required": [ "min", "max", "step", "default", "unitSymbol", "currency", "op" ], "additionalProperties": false } }, "required": [ "id", "type", "title", "help", "showIf", "any", "answers", "range" ], "additionalProperties": false } }, "result": { "type": "object", "properties": { "count": { "type": "integer" }, "bestBadge": { "nullable": true, "type": "string" }, "showPrices": { "type": "boolean" } }, "required": [ "count", "bestBadge", "showPrices" ], "additionalProperties": false }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "locale", "productType", "intro", "questions", "result", "updatedAt" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/advisors/{id}/result": { "get": { "tags": [ "Guidance and recommendations" ], "summary": "Product advisor result (answers in the URL)", "description": "Evaluates a visitor’s answers and returns the matching products with ranking, points and reasons. The answers go into the URL as `a[]=`, for example `?a[q1]=250&a[q2]=bl&a[q3]=bosch,makita`. Unknown questions and answers are ignored, sliders are clamped to their range. If there is no perfect match, `relaxed` shows which wishes were loosened. The same works with `postAdvisorResult` and the answers in the body.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getAdvisorResult", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Identifier of the product advisor." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (default) considers all products of your account, `site` only the products your website already shows. `site` only works with a site key (otherwise status 403)." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] }, "in": "query", "name": "count", "required": false, "description": "With `true` the answers are counted in the advisor’s statistics." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "advisor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "updatedAt" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rank": { "type": "integer" }, "score": { "type": "integer" }, "points": { "type": "number" }, "best": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "productId", "rank", "score", "points", "best", "reasons", "product" ], "additionalProperties": false } }, "total": { "type": "integer" }, "relaxed": { "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "questionId", "question", "answer" ], "additionalProperties": false } }, "message": { "nullable": true, "type": "string" }, "bestBadge": { "nullable": true, "type": "string" }, "answers": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" } ] } } }, "required": [ "advisor", "items", "total", "relaxed", "message", "bestBadge", "answers" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Guidance and recommendations" ], "summary": "Evaluate the product advisor result", "description": "Evaluates a visitor’s answers and returns the matching products with ranking, points and reasons. If there is no perfect match, `relaxed` shows which wishes were loosened.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "postAdvisorResult", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Identifier of the product advisor." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (default) considers all products of your account, `site` only the products your website already shows. `site` only works with a site key (otherwise status 403)." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] }, "in": "query", "name": "count", "required": false, "description": "With `true` the answers are counted in the advisor’s statistics." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "default": {}, "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "maxItems": 12, "type": "array", "items": { "type": "string", "maxLength": 16 } }, { "type": "number" } ] }, "description": "Answers per question: question identifier → chosen option, list of options or number (slider)." } } } } }, "description": "The visitor’s answers." }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "advisor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "updatedAt" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rank": { "type": "integer" }, "score": { "type": "integer" }, "points": { "type": "number" }, "best": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "productId", "rank", "score", "points", "best", "reasons", "product" ], "additionalProperties": false } }, "total": { "type": "integer" }, "relaxed": { "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "questionId", "question", "answer" ], "additionalProperties": false } }, "message": { "nullable": true, "type": "string" }, "bestBadge": { "nullable": true, "type": "string" }, "answers": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" } ] } } }, "required": [ "advisor", "items", "total", "relaxed", "message", "bestBadge", "answers" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/advisors/{id}/events": { "post": { "tags": [ "Guidance and recommendations" ], "summary": "Report product advisor statistics", "description": "Reports events of a visitor in the product advisor (for example started, question answered, result seen). The response is empty.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "reportAdvisorEvents", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Identifier of the product advisor." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "minItems": 1, "maxItems": 28, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reach", "next", "click" ] }, "question": { "type": "string", "pattern": "^[a-z0-9]{1,16}$" } }, "required": [ "type" ] }, "description": "List of events." } }, "required": [ "events" ] } } }, "description": "The events." }, "responses": { "204": { "description": "Successful, no response data", "content": { "application/json": { "schema": { "type": "string", "nullable": true, "enum": [ null ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/banners": { "get": { "tags": [ "Banners, looks and cart" ], "summary": "Get banners", "description": "Returns banners from your partner programs – specific banners, the banners of a program or the selection of a banner placement from the dashboard. Available depending on your plan.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getBanners", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 800 }, "in": "query", "name": "id", "required": false, "description": "Banner IDs, comma-separated." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "shop", "required": false, "description": "Only banners of this shop (shop ID)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "program", "required": false, "description": "Only banners of this partner program (name)." }, { "schema": { "type": "string", "enum": [ "adcell", "webgains", "awin", "tradedoubler", "ebay", "other" ] }, "in": "query", "name": "network", "required": false, "description": "Only banners of this network: `adcell`, `webgains`, `awin`, `tradedoubler`, `ebay` or `other`." }, { "schema": { "default": 5, "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of banners (1 to 20). Default: 5." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "placement", "required": false, "description": "ID of a placement from the dashboard; its rules decide the selection." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 4000 }, "in": "query", "name": "width", "required": false, "description": "Width of the available space in pixels. Formats that fit are preferred." }, { "schema": { "type": "string", "pattern": "^(\\d{2,4}x\\d{2,4}|horizontal|vertical|square)$" }, "in": "query", "name": "format", "required": false, "description": "Only banners in this format, for example `300x250`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "network": { "type": "string", "enum": [ "adcell", "webgains", "awin", "tradedoubler", "ebay", "other" ] }, "shop": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false }, "program": { "nullable": true, "type": "string" }, "delivery": { "type": "string", "enum": [ "cdn", "network" ] }, "language": { "nullable": true, "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } }, "startsAt": { "nullable": true, "type": "string" }, "endsAt": { "nullable": true, "type": "string" }, "score": { "default": null, "nullable": true, "type": "number" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "kind": { "type": "string", "enum": [ "image", "html" ] }, "url": { "nullable": true, "type": "string" }, "originalUrl": { "nullable": true, "type": "string" }, "code": { "nullable": true, "type": "string" }, "clickUrl": { "nullable": true, "type": "string" } }, "required": [ "id", "width", "height", "kind", "url", "originalUrl", "code", "clickUrl" ], "additionalProperties": false } } }, "required": [ "id", "name", "network", "shop", "program", "delivery", "language", "countries", "startsAt", "endsAt", "score", "variants" ], "additionalProperties": false } }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/banners/stats": { "post": { "tags": [ "Banners, looks and cart" ], "summary": "Report banner views and clicks", "description": "Reports impressions and clicks on banners when you display banners yourself. Counted per banner and day.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "reportBannerStats", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "v": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100 }, "p": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ] }, "description": "List of rows with banner, event and count." } }, "required": [ "rows" ] } } }, "description": "The numbers per banner." }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "recorded": { "type": "integer" } }, "required": [ "recorded" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/looks/{code}": { "get": { "tags": [ "Banners, looks and cart" ], "summary": "Get a Shop-my-Look", "description": "Returns a “look”: an image with tagged products that lead to the shop on click. Available depending on your plan.\n\nPermission for API clients: one of `catalog:read` or `products:read`. Site keys may always use this route.", "operationId": "getLook", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9]{10}$" }, "in": "path", "name": "code", "required": true, "description": "Code of the look (10 characters, lowercase letters and digits) from the dashboard." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "default": "api", "type": "string", "enum": [ "wordpress", "api" ] }, "in": "query", "name": "src", "required": false, "description": "Where the clicks should be attributed in reporting: `api` (default) or `wordpress`." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "country": { "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "width": { "nullable": true, "type": "integer" }, "height": { "nullable": true, "type": "integer" }, "alt": { "type": "string" }, "caption": { "nullable": true, "type": "string" }, "hotspots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "x": { "type": "number" }, "y": { "type": "number" }, "label": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "id", "number", "x", "y", "label", "available" ], "additionalProperties": false } } }, "required": [ "id", "url", "width", "height", "alt", "caption", "hotspots" ], "additionalProperties": false } }, "items": { "type": "array", "items": { "type": "object", "properties": { "hotspotId": { "type": "string" }, "imageId": { "type": "string" }, "number": { "type": "integer" }, "label": { "type": "string" }, "title": { "type": "string" }, "image": { "nullable": true, "type": "object", "properties": { "url": { "type": "string" }, "alt": { "type": "string" } }, "required": [ "url", "alt" ], "additionalProperties": false }, "price": { "nullable": true, "type": "string" }, "oldPrice": { "nullable": true, "type": "string" }, "priceCheckedAt": { "nullable": true, "type": "string" }, "shop": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ], "additionalProperties": false }, "target": { "type": "string", "enum": [ "offer", "search", "link", "none" ] }, "url": { "nullable": true, "type": "string" }, "amazon": { "type": "boolean" } }, "required": [ "hotspotId", "imageId", "number", "label", "title", "image", "price", "oldPrice", "priceCheckedAt", "shop", "target", "url", "amazon" ], "additionalProperties": false } }, "amazon": { "type": "boolean" }, "associates": { "type": "boolean" }, "publisher": { "type": "string" } }, "required": [ "code", "title", "description", "url", "country", "images", "items", "amazon", "associates", "publisher" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/cart": { "get": { "tags": [ "Banners, looks and cart" ], "summary": "Cart link for several products", "description": "Creates a link that puts several products into the Amazon cart at once. Products without a matching Amazon offer are listed in `skipped`.\n\nPermission for API clients: `products:read`. Site keys may always use this route.", "operationId": "getCart", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "ids", "required": true, "description": "Product identifiers, comma-separated (at most 10)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Language of the texts, for example `de-DE` or `en-GB`. Without it the default language of your website or account applies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Country for offers, prices and availability as a country code, for example `DE`, `AT` or `CH`. Without it the default country applies." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Only consider these shops: shop types or shop IDs, comma-separated, for example `amazon,awin`. Overrides your website’s rule." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Preferred shop: shop type or shop ID, several in order, comma-separated. The preferred shop counts as the best offer as long as it has the product in stock." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplace": { "nullable": true, "type": "string" }, "url": { "nullable": true, "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "title": { "type": "string" }, "asin": { "type": "string" }, "cartUrl": { "type": "string" } }, "required": [ "productId", "title", "asin", "cartUrl" ], "additionalProperties": false } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "reason": { "type": "string", "enum": [ "no_cart_offer", "other_marketplace", "limit" ] } }, "required": [ "productId", "reason" ], "additionalProperties": false } }, "missing": { "type": "array", "items": { "type": "string" } }, "maxItems": { "type": "number", "enum": [ 10 ] } }, "required": [ "marketplace", "url", "items", "skipped", "missing", "maxItems" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-requests": { "post": { "tags": [ "Product requests" ], "summary": "Request a product", "description": "Requests a product that is not in the catalog yet (or that you want to match reliably). You say what to look for – search term, EAN, ASIN, address, brand or model number. Known products are recognized immediately, otherwise affilinode searches the shops.\n\nThe response has status 200 when the request is complete, otherwise 202 with the request ID: query the state with `getProductRequest` or wait up to 15 seconds for the result with `wait`. With the `Idempotency-Key` header a repeated call is not executed twice. The number of requests per day is limited.\n\nPermission for API clients: `requests:write`. Site keys may always use this route.", "operationId": "createProductRequest", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 15 }, "in": "query", "name": "wait", "required": false, "description": "Seconds the request waits for completion (0 to 15). Default: 0.", "example": 10 }, { "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "in": "header", "name": "idempotency-key", "required": false, "description": "Unique value (8 to 100 characters) for this request. If you repeat the call with the same value you get the existing request back." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "allOf": [ { "$ref": "#/components/schemas/ProductRequestTargetInput" } ], "description": "What to look for. At least one entry is required." }, "constraints": { "type": "object", "properties": { "productType": { "type": "string", "maxLength": 64, "description": "Key of the product type, for example `smartphone`." }, "condition": { "type": "string", "enum": [ "new", "any" ], "description": "`new` (new goods only) or `any` (used as well)." }, "priceMax": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000, "description": "Maximum price." } }, "description": "Restrictions for the search." }, "countries": { "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "Country codes in which offers are searched, for example `[\"DE\",\"AT\"]` (at most 20). Default: the country of your website or account." }, "locales": { "maxItems": 10, "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" }, "description": "Languages for the product texts, for example `[\"de-DE\"]`." }, "selection": { "default": "auto", "type": "string", "enum": [ "auto", "best_effort", "manual" ], "description": "Choice when there are several matches: `auto` (only create clear matches, default), `best_effort` (take the best match) or `manual` (you always choose yourself with `selectProductRequestCandidate`)." }, "callbackUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "HTTPS address notified on completion." }, "callbackSecret": { "type": "string", "minLength": 16, "maxLength": 200, "description": "Shared secret (16 to 200 characters) used to sign the notification. Without it the notification is sent unsigned. The secret is never returned." } }, "required": [ "input" ] }, "example": { "input": { "query": "Nova X5 128 GB", "brand": "Nova" }, "constraints": { "productType": "smartphone", "condition": "new" }, "countries": [ "DE" ], "selection": "auto" } } }, "description": "What to look for and how the choice should be made." }, "responses": { "200": { "description": "The request is complete (or was already known).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "id": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "input": { "query": "Nova X5 128 GB" }, "status": "completed", "productId": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "match": { "method": "search", "confidence": 0.97, "notes": [] }, "candidates": [], "llmCheck": null, "error": null, "createdAt": "2026-10-19T08:00:00.000Z", "completedAt": "2026-10-19T08:00:06.000Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "202": { "description": "The request was accepted and is being processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "id": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "input": { "query": "Nova X5 128 GB" }, "status": "searching", "productId": null, "match": null, "candidates": [], "llmCheck": null, "error": null, "createdAt": "2026-10-19T08:00:00.000Z", "completedAt": null } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "Product requests" ], "summary": "List product requests", "description": "Returns your product requests, newest first.\n\nPermission for API clients: `requests:write`. Site keys may always use this route.", "operationId": "getProductRequests", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "status", "required": false, "description": "Only requests with this status, comma-separated: `queued`, `searching`, `selecting`, `completed`, `needs_selection`, `not_found`, `failed`, `rejected`." }, { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of requests (1 to 100). Default: 25." }, { "schema": { "type": "string", "maxLength": 60 }, "in": "query", "name": "cursor", "required": false, "description": "Continuation: the `nextCursor` value from the previous response. Without it the list starts from the beginning." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRequest" } }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "requests", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-requests/{id}": { "get": { "tags": [ "Product requests" ], "summary": "Get a product request", "description": "Returns the state of a request. With `wait` you wait up to 15 seconds for completion. Status 200 means complete, 202 means in progress. With `needs_selection` the candidates are in `candidates`.\n\nPermission for API clients: `requests:write`. Site keys may always use this route.", "operationId": "getProductRequest", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Request ID from `createProductRequest`.", "example": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 15 }, "in": "query", "name": "wait", "required": false, "description": "Seconds the request waits for completion (0 to 15). Default: 0.", "example": 5 }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "The request is complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "id": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "input": { "query": "Nova X5 128 GB" }, "status": "completed", "productId": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "match": { "method": "search", "confidence": 0.97, "notes": [] }, "candidates": [], "llmCheck": null, "error": null, "createdAt": "2026-10-19T08:00:00.000Z", "completedAt": "2026-10-19T08:00:06.000Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "202": { "description": "The request is still being processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "id": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "input": { "query": "Nova X5 128 GB" }, "status": "searching", "productId": null, "match": null, "candidates": [], "llmCheck": null, "error": null, "createdAt": "2026-10-19T08:00:00.000Z", "completedAt": null } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-requests/{id}/reject": { "post": { "tags": [ "Product requests" ], "summary": "Reject a product request", "description": "Ends a request whose candidates do not fit. No product is assigned.\n\nPermission for API clients: `requests:write`. Site keys may always use this route.", "operationId": "rejectProductRequest", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Request ID." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 300, "description": "Short reason (at most 300 characters)." } } } } }, "description": "Optional reason." }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-requests/{id}/select": { "post": { "tags": [ "Product requests" ], "summary": "Choose a candidate for a product request", "description": "Chooses the matching candidate for a request with status `needs_selection`. The product is then created or assigned.\n\nPermission for API clients: `requests:write`. Site keys may always use this route.", "operationId": "selectProductRequestCandidate", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Request ID." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "candidate": { "type": "string", "maxLength": 200, "description": "Identifier of the candidate (`ref` from the `candidates` list)." }, "productType": { "type": "string", "maxLength": 64, "description": "Optional: key of the product type if it should be set." }, "singleCandidate": { "type": "string", "maxLength": 200, "description": "Optional: identifier of the single product if the candidate is a multipack." } }, "required": [ "candidate" ] } } }, "description": "The chosen candidate." }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/reporting/summary": { "get": { "tags": [ "Reporting" ], "summary": "Reporting: summary", "description": "Returns clicks, impressions, orders, revenue and commission (confirmed and open) for a period, grouped by day, website, shop, product, article or other. A site key only sees the figures of its own website.\n\nPermission for API clients: `reporting:read`. Site keys may always use this route.", "operationId": "getReportingSummary", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "reporting:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": true, "description": "Start of the period as a date `YYYY-MM-DD`." }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": true, "description": "End of the period as a date `YYYY-MM-DD` (inclusive)." }, { "schema": { "default": "day", "type": "string", "enum": [ "day", "site", "subsite", "shop", "advertiser", "product", "article", "box", "account", "source", "country" ] }, "in": "query", "name": "groupBy", "required": false, "description": "Grouping of the rows: `day`, `site`, `subsite`, `shop`, `advertiser`, `product`, `article`, `box`, `account`, `source` or `country`." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "accountId", "required": false, "description": "Only this partner account." }, { "schema": { "type": "string", "enum": [ "awin", "amazon", "ebay", "adsense", "matomo", "ga4", "tradedoubler", "adcell", "webgains", "levanta", "partnerboost", "impact", "archer" ] }, "in": "query", "name": "source", "required": false, "description": "Only this source, for example `awin` or `amazon`." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "siteId", "required": false, "description": "Only this website." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "in": "query", "name": "blogId", "required": false, "description": "Only this subsite of a WordPress network." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "shopId", "required": false, "description": "Only this shop." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Only this product." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "articleKey", "required": false, "description": "Only this article (identifier from the WordPress plugin)." }, { "schema": { "type": "string", "pattern": "^[a-z_]{1,20}$" }, "in": "query", "name": "boxKind", "required": false, "description": "Only this kind of box." }, { "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "in": "query", "name": "currency", "required": false, "description": "Currency in which totals are reported, for example `EUR`." }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of rows (1 to 500). Default: 100." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "groupBy": { "type": "string", "enum": [ "day", "site", "subsite", "shop", "advertiser", "product", "article", "box", "account", "source", "country" ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "orders": { "type": "integer" }, "items": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" }, "pendingRevenue": { "type": "string" }, "pendingCommission": { "type": "string" }, "declinedRevenue": { "type": "string" }, "declinedCommission": { "type": "string" }, "key": { "nullable": true, "type": "string" }, "label": { "type": "string" }, "currency": { "type": "string" }, "blogId": { "nullable": true, "type": "integer" } }, "required": [ "clicks", "impressions", "orders", "items", "revenue", "commission", "pendingRevenue", "pendingCommission", "declinedRevenue", "declinedCommission", "key", "label", "currency", "blogId" ], "additionalProperties": false } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "orders": { "type": "integer" }, "items": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" }, "pendingRevenue": { "type": "string" }, "pendingCommission": { "type": "string" }, "declinedRevenue": { "type": "string" }, "declinedCommission": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "clicks", "impressions", "orders", "items", "revenue", "commission", "pendingRevenue", "pendingCommission", "declinedRevenue", "declinedCommission", "currency" ], "additionalProperties": false } }, "unmatched": { "type": "object", "properties": { "rows": { "type": "integer" }, "clicks": { "type": "integer" }, "orders": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" } }, "required": [ "rows", "clicks", "orders", "revenue", "commission" ], "additionalProperties": false }, "truncated": { "type": "boolean" } }, "required": [ "from", "to", "groupBy", "rows", "totals", "unmatched", "truncated" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/reporting/revenue": { "get": { "tags": [ "Reporting" ], "summary": "Reporting: revenue", "description": "Returns revenue for a period, grouped for example by article, box, product or shop, with page views. `truncated` shows whether the rows were shortened.\n\nPermission for API clients: `reporting:read`. Site keys may always use this route.", "operationId": "getReportingRevenue", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "reporting:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": true, "description": "Start of the period as a date `YYYY-MM-DD`." }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": true, "description": "End of the period as a date `YYYY-MM-DD` (inclusive)." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "siteId", "required": false, "description": "Only this website." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "in": "query", "name": "blogId", "required": false, "description": "Only this subsite of a WordPress network." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "shopId", "required": false, "description": "Only this shop." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Only this product." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "articleKey", "required": false, "description": "Only this article (identifier from the WordPress plugin)." }, { "schema": { "type": "string", "pattern": "^[a-z_]{1,20}$" }, "in": "query", "name": "boxKind", "required": false, "description": "Only this kind of box." }, { "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "in": "query", "name": "currency", "required": false, "description": "Currency, for example `EUR`." }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of rows (1 to 500). Default: 100." }, { "schema": { "default": "article", "type": "string", "enum": [ "article", "box", "product", "shop", "source", "advertiser", "country", "site", "day" ] }, "in": "query", "name": "groupBy", "required": false, "description": "Grouping: `article`, `box`, `product`, `shop`, `source`, `advertiser`, `country`, `site` or `day`." }, { "schema": { "type": "string", "enum": [ "awin", "amazon", "ebay", "tradedoubler", "adcell", "webgains", "impact", "levanta", "partnerboost", "archer" ] }, "in": "query", "name": "source", "required": false, "description": "Only this source, for example `awin` or `amazon`." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Only this country (country code)." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "groupBy": { "type": "string", "enum": [ "article", "box", "product", "shop", "source", "advertiser", "country", "site", "day" ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "integer" }, "orders": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" }, "pendingCommission": { "type": "string" }, "approvedCommission": { "type": "string" }, "declinedCommission": { "type": "string" }, "epc": { "nullable": true, "type": "string" }, "conversionRate": { "nullable": true, "type": "number" }, "pageviews": { "nullable": true, "type": "integer" }, "commissionPer1000": { "nullable": true, "type": "string" }, "key": { "nullable": true, "type": "string" }, "label": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "clicks", "orders", "revenue", "commission", "pendingCommission", "approvedCommission", "declinedCommission", "epc", "conversionRate", "pageviews", "commissionPer1000", "key", "label", "currency" ], "additionalProperties": false } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "integer" }, "orders": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" }, "pendingCommission": { "type": "string" }, "approvedCommission": { "type": "string" }, "declinedCommission": { "type": "string" }, "epc": { "nullable": true, "type": "string" }, "conversionRate": { "nullable": true, "type": "number" }, "pageviews": { "nullable": true, "type": "integer" }, "commissionPer1000": { "nullable": true, "type": "string" }, "currency": { "type": "string" } }, "required": [ "clicks", "orders", "revenue", "commission", "pendingCommission", "approvedCommission", "declinedCommission", "epc", "conversionRate", "pageviews", "commissionPer1000", "currency" ], "additionalProperties": false } }, "pageviews": { "nullable": true, "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "from", "to", "groupBy", "rows", "totals", "pageviews", "truncated" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/short-links": { "post": { "tags": [ "Short links" ], "summary": "Create a short link", "description": "Creates a short link for a product (`product`, target per visitor country according to your rules) or for an address (`url`). Preferred slug, group, note and UTM values are optional. Available depending on your plan.\n\nOnly with a site key, because a short link belongs to a website. With an API client the route responds with status 403.", "operationId": "createShortLink", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Identifier of the product (link with a target per country)." }, "url": { "type": "string", "maxLength": 2000, "description": "Address the link points to." }, "channel": { "type": "string", "pattern": "^[a-z0-9_]{1,32}$", "description": "Channel for reporting, for example `instagram`." }, "title": { "type": "string", "maxLength": 200, "description": "Title of the link in the overview." }, "overview": { "type": "boolean", "description": "With `true` the link shows an overview of all offers instead of going straight to the best one." }, "slug": { "type": "string", "description": "Preferred slug for the short link address." }, "group": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Name of the group the link appears in (created if needed)." }, "note": { "type": "string", "maxLength": 1000, "description": "Internal note." }, "utm": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 100, "description": "utm_source" }, "medium": { "type": "string", "minLength": 1, "maxLength": 100, "description": "utm_medium" }, "campaign": { "type": "string", "minLength": 1, "maxLength": 100, "description": "utm_campaign" }, "content": { "type": "string", "minLength": 1, "maxLength": 100, "description": "utm_content" } }, "description": "UTM values appended to the target address." }, "routing": { "type": "object", "properties": { "rules": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{1,12}$" }, "label": { "default": "", "type": "string", "maxLength": 80 }, "active": { "default": true, "type": "boolean" }, "when": { "type": "object", "properties": { "countries": { "default": [], "maxItems": 60, "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "devices": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "mobile", "tablet", "desktop" ] } }, "os": { "default": [], "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux" ] } }, "languages": { "default": [], "maxItems": 30, "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}$" } }, "days": { "default": [], "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "timeFrom": { "default": null, "nullable": true, "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "timeTo": { "default": null, "nullable": true, "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "default", "url", "offer", "overview" ] }, "url": { "default": null, "nullable": true, "type": "string", "maxLength": 2000 }, "offerId": { "default": null, "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind" ] } }, "required": [ "id", "when", "target" ] } }, "ab": { "default": null, "nullable": true, "type": "object", "properties": { "variants": { "minItems": 2, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{1,12}$" }, "label": { "default": "", "type": "string", "maxLength": 80 }, "weight": { "type": "integer", "minimum": 0, "maximum": 100 }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "default", "url", "offer", "overview" ] }, "url": { "default": null, "nullable": true, "type": "string", "maxLength": 2000 }, "offerId": { "default": null, "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind" ] } }, "required": [ "id", "weight", "target" ] } }, "winner": { "default": null, "nullable": true, "type": "string", "pattern": "^[a-z0-9]{1,12}$" }, "startedAt": { "default": null, "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "variants" ] } }, "description": "Rules for the target per visitor country and A/B test." } }, "required": [ "channel" ] } } }, "description": "Target and details of the link. Either `product` or `url` must be given." }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "code": { "type": "string" }, "shortUrl": { "type": "string" }, "title": { "type": "string" }, "targetUrl": { "default": "", "type": "string" }, "mode": { "default": "redirect", "type": "string", "enum": [ "redirect", "direct" ] }, "notes": { "type": "array", "items": { "type": "string" } }, "codes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sponsor": { "type": "string" }, "code": { "type": "string" }, "discountText": { "nullable": true, "type": "string" }, "endsAt": { "nullable": true, "type": "string" }, "text": { "type": "string" } }, "required": [ "id", "sponsor", "code", "discountText", "endsAt", "text" ], "additionalProperties": false } } }, "required": [ "id", "code", "shortUrl", "title", "targetUrl", "mode", "notes", "codes" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "schemas": { "CatalogFacet": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "values" ] }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "value", "label", "count" ], "additionalProperties": false } } }, "required": [ "key", "type", "label", "values" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "range" ] }, "label": { "type": "string" }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" }, "count": { "type": "integer" }, "unit": { "nullable": true, "type": "string" } }, "required": [ "key", "type", "label", "min", "max", "count", "unit" ], "additionalProperties": false } ] }, "CatalogProduct": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "model": { "nullable": true, "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "activityState": { "type": "string", "enum": [ "catalog", "active", "paused" ] }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ] }, "image": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "keySpecs": { "type": "array", "items": { "$ref": "#/components/schemas/SpecItem" } }, "specCount": { "type": "integer" }, "completeness": { "$ref": "#/components/schemas/SpecCompleteness" }, "bestPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "offerCount": { "type": "integer" }, "popularity": { "type": "object", "properties": { "clicks30d": { "type": "integer" }, "impressions30d": { "type": "integer" }, "orders30d": { "type": "integer" }, "sites": { "type": "integer" }, "lastRequestedAt": { "nullable": true, "type": "string" } }, "required": [ "clicks30d", "impressions30d", "orders30d", "sites", "lastRequestedAt" ], "additionalProperties": false }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "brand", "model", "productType", "activityState", "status", "image", "keySpecs", "specCount", "completeness", "bestPrice", "offerCount", "popularity", "updatedAt" ], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable code, for example `validation_failed`, `unauthorized`, `forbidden`, `not_found`." }, "message": { "type": "string", "description": "Explanation for humans (in German)." }, "details": { "description": "Further details, for example the faulty fields for `validation_failed`." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "The error." } }, "required": [ "error" ], "additionalProperties": false, "description": "Structure of all error responses." }, "Image": { "type": "object", "properties": { "url": { "type": "string", "description": "Address of the image in standard size." }, "width": { "nullable": true, "type": "integer", "description": "Width in pixels." }, "height": { "nullable": true, "type": "integer", "description": "Height in pixels." }, "alt": { "type": "string", "description": "Alternative text for accessibility." }, "srcset": { "nullable": true, "type": "string", "description": "Ready-made `srcset` value with size variants, if available." }, "source": { "type": "string", "enum": [ "cdn", "origin" ] }, "imageRights": { "type": "string", "enum": [ "rehost", "hotlink", "none" ] }, "editRights": { "type": "string", "enum": [ "edit", "none" ] }, "cutout": { "nullable": true, "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "url", "width", "height" ], "additionalProperties": false } }, "required": [ "url", "width", "height", "alt", "srcset", "source", "imageRights", "editRights", "cutout" ], "additionalProperties": false, "description": "A product image." }, "ListItem": { "type": "object", "properties": { "position": { "type": "integer" }, "badge": { "nullable": true, "type": "string" }, "note": { "nullable": true, "type": "string" }, "product": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "required": [ "position", "badge", "note", "product" ], "additionalProperties": false }, "Money": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount as a decimal number in text form, for example `399.00`." }, "currency": { "type": "string", "description": "Currency as ISO code, for example `EUR`." }, "formatted": { "type": "string", "description": "Ready-formatted for display, for example `399,00 €`." } }, "required": [ "amount", "currency", "formatted" ], "additionalProperties": false, "description": "An amount of money." }, "Offer": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the offer." }, "shop": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ], "description": "Kind of shop or network." }, "name": { "type": "string", "description": "Name of the shop." }, "logoUrl": { "nullable": true, "type": "string", "description": "Address of the shop logo, if available." }, "own": { "type": "boolean", "description": "Is `true` for your own shop (no partner program)." } }, "required": [ "id", "type", "name", "logoUrl", "own" ], "additionalProperties": false, "description": "The shop making the offer." }, "country": { "type": "string", "description": "Country the offer applies to." }, "title": { "nullable": true, "type": "string", "description": "Title of the offer in the shop." }, "url": { "type": "string", "description": "Affiliate link to the offer with your tracking IDs." }, "cartUrl": { "default": null, "nullable": true, "type": "string", "description": "Link that puts the product straight into the cart (only for shops that support it)." }, "price": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Price without shipping." }, "oldPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Struck-through earlier price, if the shop states one." }, "shipping": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Shipping cost, if known." }, "total": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Price including shipping." }, "savings": { "nullable": true, "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "percent": { "type": "integer" } }, "required": [ "amount", "percent" ], "additionalProperties": false, "description": "Saving compared with the earlier price." }, "availability": { "type": "string", "enum": [ "in_stock", "limited", "preorder", "out_of_stock", "unknown" ], "description": "Availability: `in_stock`, `limited`, `preorder`, `out_of_stock` or `unknown`." }, "availabilityText": { "nullable": true, "type": "string", "description": "Availability as stated by the shop." }, "delivery": { "nullable": true, "type": "object", "properties": { "text": { "type": "string" }, "minDays": { "nullable": true, "type": "integer" }, "maxDays": { "nullable": true, "type": "integer" }, "fast": { "type": "boolean" } }, "required": [ "text", "minDays", "maxDays", "fast" ], "additionalProperties": false, "description": "Delivery time." }, "condition": { "type": "string", "enum": [ "new", "used", "refurbished" ], "description": "Condition: `new`, `used` or `refurbished`." }, "conditionDetail": { "default": null, "nullable": true, "type": "string", "enum": [ "open_box", "b_stock", "returned", "demo", "like_new", "very_good", "good", "acceptable", "for_parts" ], "description": "Detail for items that are not new: `open_box`, `b_stock`, `returned`, `demo`, `like_new`, `very_good`, `good`, `acceptable` or `for_parts`; otherwise `null`." }, "checkedAt": { "type": "string", "description": "Time of the last price check." }, "priceAgeHours": { "default": null, "nullable": true, "type": "integer", "minimum": 0, "description": "Age of the price in whole hours, `null` without a check time. An older price stays visible with this value; the display hides Amazon and eBay prices after 24 and 6 hours." }, "priceStale": { "default": false, "type": "boolean", "description": "`true` when the price is older than the threshold for its shop type. Such offers are never the best offer, and their availability is `unknown`." }, "isBest": { "type": "boolean", "description": "Is `true` for the best offer for the country." }, "packQuantity": { "default": 1, "type": "integer", "minimum": 1, "description": "Number of pieces in the pack." }, "unitPrice": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Price per unit (for example per piece), if it can be calculated." }, "priceInsight": { "default": null, "nullable": true, "type": "object", "properties": { "lowestInDays": { "nullable": true, "type": "integer" }, "dropPercent": { "nullable": true, "type": "integer" }, "dropSince": { "nullable": true, "type": "string" } }, "required": [ "lowestInDays", "dropPercent", "dropSince" ], "additionalProperties": false, "description": "Assessment of the price against its history." }, "salesRank": { "default": null, "nullable": true, "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1 }, "category": { "nullable": true, "type": "string" } }, "required": [ "rank", "category" ], "additionalProperties": false } }, "required": [ "id", "shop", "country", "title", "url", "cartUrl", "price", "oldPrice", "shipping", "total", "savings", "availability", "availabilityText", "delivery", "condition", "conditionDetail", "checkedAt", "priceAgeHours", "priceStale", "isBest", "packQuantity", "unitPrice", "priceInsight", "salesRank" ], "additionalProperties": false, "description": "A shop’s offer for a product, with price and affiliate link." }, "Product": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the product at affilinode." }, "title": { "type": "string", "description": "Display title of the product." }, "detailedTitle": { "default": null, "nullable": true, "type": "string", "description": "Detailed title with brand, model, product type and main attributes." }, "brand": { "nullable": true, "type": "string", "description": "Brand." }, "mpn": { "nullable": true, "type": "string", "description": "Manufacturer model number." }, "gtins": { "type": "array", "items": { "type": "string" }, "description": "EAN or UPC numbers." }, "productClass": { "type": "string", "enum": [ "goods", "service", "tariff" ], "description": "Kind of product: `goods`, `service` or `tariff`." }, "productType": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the product type." }, "label": { "type": "string", "description": "Name of the product type." }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "path" ], "additionalProperties": false, "description": "Standardized product type, for example smartphone." }, "category": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false, "description": "Your own category for the product, if assigned." }, "locale": { "type": "string", "description": "Language of the delivered texts." }, "textLocales": { "default": null, "nullable": true, "type": "object", "properties": { "title": { "nullable": true, "type": "string" }, "detailedTitle": { "nullable": true, "type": "string" }, "short": { "nullable": true, "type": "string" }, "long": { "nullable": true, "type": "string" } }, "required": [ "title", "detailedTitle", "short", "long" ], "additionalProperties": false, "description": "Language of the individual texts if it differs from `locale` (then the translation was missing)." }, "country": { "type": "string", "description": "Country the offers and prices apply to." }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" }, "description": "Product images." }, "badge": { "nullable": true, "type": "string", "description": "Editorial badge, for example “Test winner”." }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "Short bullet points on the main features." }, "texts": { "type": "object", "properties": { "short": { "nullable": true, "type": "string" }, "long": { "nullable": true, "type": "string" }, "verdict": { "default": null, "nullable": true, "type": "string" }, "social": { "default": null, "nullable": true, "type": "string" } }, "required": [ "short", "long", "verdict", "social" ], "additionalProperties": false, "description": "Descriptive texts: short text, long text, verdict and social media text." }, "aiTexts": { "default": null, "nullable": true, "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string", "enum": [ "short", "long", "prosCons", "verdict", "social" ] } }, "label": { "type": "boolean" } }, "required": [ "fields", "label" ], "additionalProperties": false, "description": "Which texts were written with AI and whether the “AI-generated” notice should be shown." }, "prosCons": { "nullable": true, "type": "object", "properties": { "pros": { "type": "array", "items": { "type": "string" } }, "cons": { "type": "array", "items": { "type": "string" } } }, "required": [ "pros", "cons" ], "additionalProperties": false, "description": "Pros and cons." }, "review": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Review" } ] }, "specs": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SpecItem" } } }, "required": [ "group", "items" ], "additionalProperties": false }, "description": "Technical attributes in groups." }, "attributions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "license": { "nullable": true, "type": "string" }, "licenseUrl": { "nullable": true, "type": "string" }, "notice": { "nullable": true, "type": "string" } }, "required": [ "source", "name", "url", "license", "licenseUrl", "notice" ], "additionalProperties": false } }, "profile": { "nullable": true, "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "partial" ] }, "locale": { "type": "string" }, "strengths": { "type": "array", "items": { "type": "string" } }, "weaknesses": { "type": "array", "items": { "type": "string" } }, "audience": { "nullable": true, "type": "string" }, "specials": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "llm", "manual" ] }, "updatedAt": { "type": "string" } }, "required": [ "status", "locale", "strengths", "weaknesses", "audience", "specials", "source", "updatedAt" ], "additionalProperties": false, "description": "Product profile with strengths, weaknesses and target audience." }, "completeness": { "allOf": [ { "$ref": "#/components/schemas/SpecCompleteness" } ], "description": "How completely the important attributes are filled in." }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" }, "description": "Offers from the shops, best first." }, "usedOffers": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Offer" }, "description": "Used, refurbished, B-stock and open-box offers, kept apart from `offers`: lowest total price first, never `isBest`, without savings or price signals. `offers` contains new goods only." }, "linkOffers": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "shop": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] }, "name": { "type": "string" }, "logoUrl": { "nullable": true, "type": "string" }, "own": { "type": "boolean" } }, "required": [ "id", "type", "name", "logoUrl", "own" ], "additionalProperties": false }, "country": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "shop", "country", "url" ], "additionalProperties": false }, "description": "Amazon as a link only: an entry without price, image, title or stock, kept apart from the offers. It never counts for the best price." }, "ebayOffers": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Offer" }, "description": "Offers from eBay (separate because they are presented differently)." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "language": { "nullable": true, "type": "string" }, "url": { "type": "string" }, "sizeBytes": { "nullable": true, "type": "integer" }, "pageCount": { "default": null, "nullable": true, "type": "integer" }, "eprelUrl": { "default": null, "nullable": true, "type": "string" } }, "required": [ "type", "title", "language", "url", "sizeBytes", "pageCount", "eprelUrl" ], "additionalProperties": false }, "description": "Documents such as data sheet or manual." }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ], "description": "Availability of the product on the market: `available`, `unavailable` or `discontinued`." }, "activityState": { "type": "string", "enum": [ "catalog", "active", "paused" ], "description": "Whether prices are updated continuously: `active`, `paused` or catalog entry only (`catalog`)." }, "offersStatus": { "type": "string", "enum": [ "available", "pending", "none" ], "description": "State of the offer search: `available` (offers exist), `pending` (being searched) or `none` (none found)." }, "updatedAt": { "type": "string", "description": "Time of the last change." }, "variantOf": { "default": null, "nullable": true, "type": "string", "description": "Identifier of the model product if this is a variant." }, "variantLabel": { "default": null, "nullable": true, "type": "string", "description": "Name of the variant, for example “Black, 256 GB”." }, "variants": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "label": { "nullable": true, "type": "string" }, "price": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "available": { "type": "boolean" }, "url": { "default": null, "nullable": true, "type": "string" }, "shopName": { "default": null, "nullable": true, "type": "string" }, "shopType": { "default": null, "nullable": true, "type": "string" }, "axes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "color": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false } }, "required": [ "key", "label", "value" ], "additionalProperties": false } }, "color": { "default": null, "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false }, "image": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "bestOffer": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Offer" } ] }, "isDefault": { "default": false, "type": "boolean" } }, "required": [ "id", "title", "label", "price", "available", "url", "shopName", "shopType", "axes", "color", "image", "bestOffer", "isDefault" ], "additionalProperties": false }, "description": "Variants of the product." }, "lowestVariant": { "default": null, "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "label": { "nullable": true, "type": "string" }, "price": { "$ref": "#/components/schemas/Money" } }, "required": [ "id", "label", "price" ], "additionalProperties": false }, "isModel": { "default": false, "type": "boolean", "description": "Is `true` if this is a model product with several variants." }, "variantAxes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "variantIds": { "type": "array", "items": { "type": "string" } }, "color": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false } }, "required": [ "value", "variantIds" ], "additionalProperties": false } } }, "required": [ "key", "label", "values" ], "additionalProperties": false } }, "priceRange": { "default": null, "nullable": true, "type": "object", "properties": { "min": { "$ref": "#/components/schemas/Money" }, "max": { "$ref": "#/components/schemas/Money" } }, "required": [ "min", "max" ], "additionalProperties": false, "description": "Price range across all variants." } }, "required": [ "id", "title", "detailedTitle", "brand", "mpn", "gtins", "productClass", "productType", "category", "locale", "textLocales", "country", "images", "badge", "highlights", "texts", "aiTexts", "prosCons", "review", "specs", "attributions", "profile", "completeness", "offers", "usedOffers", "linkOffers", "ebayOffers", "documents", "status", "activityState", "offersStatus", "updatedAt", "variantOf", "variantLabel", "variants", "lowestVariant", "isModel", "variantAxes", "priceRange" ], "additionalProperties": false, "description": "A product with texts, images, attributes and the current offers from the shops. Fields without a value are `null` or empty lists." }, "ProductRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Request ID." }, "input": { "allOf": [ { "$ref": "#/components/schemas/ProductRequestTarget" } ], "description": "What was looked for." }, "status": { "type": "string", "enum": [ "queued", "searching", "selecting", "completed", "needs_selection", "not_found", "failed", "rejected" ], "description": "State: `queued` (waiting), `searching` (search running), `selecting` (selection running), `completed` (done), `needs_selection` (you need to choose), `not_found` (nothing found), `failed` (failed), `rejected` (rejected)." }, "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of the assigned product once the request is complete." }, "match": { "nullable": true, "type": "object", "properties": { "method": { "type": "string", "enum": [ "gtin", "asin", "mpn", "previous_request", "search", "manual", "llm", "pack", "tariff", "manual_link" ] }, "confidence": { "type": "number" }, "notes": { "type": "array", "items": { "type": "string" } }, "packCount": { "nullable": true, "type": "integer" }, "tariffOffers": { "type": "integer" }, "tariffName": { "nullable": true, "type": "string" } }, "required": [ "method", "confidence", "notes" ], "additionalProperties": false, "description": "How the product was found." }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRequestCandidate" }, "description": "Candidates to choose from (status `needs_selection`)." }, "llmCheck": { "nullable": true, "type": "object", "properties": { "choice": { "nullable": true, "type": "string" }, "confidence": { "type": "number" }, "reason": { "type": "string" }, "checkedAt": { "type": "string" } }, "required": [ "choice", "confidence", "reason", "checkedAt" ], "additionalProperties": false }, "error": { "nullable": true, "type": "string", "description": "Error message if the request failed." }, "createdAt": { "type": "string", "description": "Time the request was created." }, "completedAt": { "nullable": true, "type": "string", "description": "Time of completion; `null` while the request is running." } }, "required": [ "id", "input", "status", "productId", "match", "candidates", "llmCheck", "error", "createdAt", "completedAt" ], "additionalProperties": false, "description": "A product request with input, state and result." }, "ProductRequestCandidate": { "type": "object", "properties": { "ref": { "type": "string" }, "shop": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] }, "name": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false }, "externalId": { "type": "string" }, "url": { "type": "string", "maxLength": 2048 }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "gtins": { "type": "array", "items": { "type": "string" } }, "mpn": { "nullable": true, "type": "string" }, "productType": { "nullable": true, "type": "string" }, "categoryPath": { "maxItems": 6, "type": "array", "items": { "type": "string" } }, "price": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } }, "packCount": { "nullable": true, "type": "integer" }, "tariff": { "type": "boolean" } }, "required": [ "ref", "shop", "externalId", "title", "brand", "gtins", "mpn", "productType", "price", "score", "reasons" ], "additionalProperties": false }, "ProductRequestTarget": { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 200 }, "gtin": { "type": "string", "maxLength": 20 }, "asin": { "type": "string", "maxLength": 20 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "brand": { "type": "string", "maxLength": 80 }, "mpn": { "type": "string", "maxLength": 80 } }, "additionalProperties": false }, "ProductRequestTargetInput": { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Free search term, for example “Bosch GSR 12V-15”." }, "gtin": { "type": "string", "maxLength": 20, "description": "EAN or UPC." }, "asin": { "type": "string", "maxLength": 20, "description": "Amazon ASIN." }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Address of a product page in the shop." }, "brand": { "type": "string", "maxLength": 80, "description": "Brand." }, "mpn": { "type": "string", "maxLength": 80, "description": "Manufacturer model number." } } }, "ProductWithReplacement": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "detailedTitle": { "default": null, "nullable": true, "type": "string" }, "brand": { "nullable": true, "type": "string" }, "mpn": { "nullable": true, "type": "string" }, "gtins": { "type": "array", "items": { "type": "string" } }, "productClass": { "type": "string", "enum": [ "goods", "service", "tariff" ] }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "path" ], "additionalProperties": false }, "category": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, "locale": { "type": "string" }, "textLocales": { "default": null, "nullable": true, "type": "object", "properties": { "title": { "nullable": true, "type": "string" }, "detailedTitle": { "nullable": true, "type": "string" }, "short": { "nullable": true, "type": "string" }, "long": { "nullable": true, "type": "string" } }, "required": [ "title", "detailedTitle", "short", "long" ], "additionalProperties": false }, "country": { "type": "string" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "badge": { "nullable": true, "type": "string" }, "highlights": { "type": "array", "items": { "type": "string" } }, "texts": { "type": "object", "properties": { "short": { "nullable": true, "type": "string" }, "long": { "nullable": true, "type": "string" }, "verdict": { "default": null, "nullable": true, "type": "string" }, "social": { "default": null, "nullable": true, "type": "string" } }, "required": [ "short", "long", "verdict", "social" ], "additionalProperties": false }, "aiTexts": { "default": null, "nullable": true, "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string", "enum": [ "short", "long", "prosCons", "verdict", "social" ] } }, "label": { "type": "boolean" } }, "required": [ "fields", "label" ], "additionalProperties": false }, "prosCons": { "nullable": true, "type": "object", "properties": { "pros": { "type": "array", "items": { "type": "string" } }, "cons": { "type": "array", "items": { "type": "string" } } }, "required": [ "pros", "cons" ], "additionalProperties": false }, "review": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Review" } ] }, "specs": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SpecItem" } } }, "required": [ "group", "items" ], "additionalProperties": false } }, "attributions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "license": { "nullable": true, "type": "string" }, "licenseUrl": { "nullable": true, "type": "string" }, "notice": { "nullable": true, "type": "string" } }, "required": [ "source", "name", "url", "license", "licenseUrl", "notice" ], "additionalProperties": false } }, "profile": { "nullable": true, "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "partial" ] }, "locale": { "type": "string" }, "strengths": { "type": "array", "items": { "type": "string" } }, "weaknesses": { "type": "array", "items": { "type": "string" } }, "audience": { "nullable": true, "type": "string" }, "specials": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "llm", "manual" ] }, "updatedAt": { "type": "string" } }, "required": [ "status", "locale", "strengths", "weaknesses", "audience", "specials", "source", "updatedAt" ], "additionalProperties": false }, "completeness": { "$ref": "#/components/schemas/SpecCompleteness" }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "usedOffers": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "linkOffers": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "shop": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] }, "name": { "type": "string" }, "logoUrl": { "nullable": true, "type": "string" }, "own": { "type": "boolean" } }, "required": [ "id", "type", "name", "logoUrl", "own" ], "additionalProperties": false }, "country": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "shop", "country", "url" ], "additionalProperties": false } }, "ebayOffers": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "language": { "nullable": true, "type": "string" }, "url": { "type": "string" }, "sizeBytes": { "nullable": true, "type": "integer" }, "pageCount": { "default": null, "nullable": true, "type": "integer" }, "eprelUrl": { "default": null, "nullable": true, "type": "string" } }, "required": [ "type", "title", "language", "url", "sizeBytes", "pageCount", "eprelUrl" ], "additionalProperties": false } }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ] }, "activityState": { "type": "string", "enum": [ "catalog", "active", "paused" ] }, "offersStatus": { "type": "string", "enum": [ "available", "pending", "none" ] }, "updatedAt": { "type": "string" }, "variantOf": { "default": null, "nullable": true, "type": "string" }, "variantLabel": { "default": null, "nullable": true, "type": "string" }, "variants": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "label": { "nullable": true, "type": "string" }, "price": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "available": { "type": "boolean" }, "url": { "default": null, "nullable": true, "type": "string" }, "shopName": { "default": null, "nullable": true, "type": "string" }, "shopType": { "default": null, "nullable": true, "type": "string" }, "axes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "color": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false } }, "required": [ "key", "label", "value" ], "additionalProperties": false } }, "color": { "default": null, "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false }, "image": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "bestOffer": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Offer" } ] }, "isDefault": { "default": false, "type": "boolean" } }, "required": [ "id", "title", "label", "price", "available", "url", "shopName", "shopType", "axes", "color", "image", "bestOffer", "isDefault" ], "additionalProperties": false } }, "lowestVariant": { "default": null, "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "label": { "nullable": true, "type": "string" }, "price": { "$ref": "#/components/schemas/Money" } }, "required": [ "id", "label", "price" ], "additionalProperties": false }, "isModel": { "default": false, "type": "boolean" }, "variantAxes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "variantIds": { "type": "array", "items": { "type": "string" } }, "color": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false } }, "required": [ "value", "variantIds" ], "additionalProperties": false } } }, "required": [ "key", "label", "values" ], "additionalProperties": false } }, "priceRange": { "default": null, "nullable": true, "type": "object", "properties": { "min": { "$ref": "#/components/schemas/Money" }, "max": { "$ref": "#/components/schemas/Money" } }, "required": [ "min", "max" ], "additionalProperties": false }, "replacement": { "nullable": true, "type": "object", "properties": { "relation": { "type": "string", "enum": [ "successor", "alternative" ] }, "reason": { "type": "string", "enum": [ "unavailable", "discontinued" ] }, "origin": { "default": "central", "type": "string", "enum": [ "site", "own", "central" ] }, "notice": { "default": "", "type": "string" }, "product": { "$ref": "#/components/schemas/Product" } }, "required": [ "relation", "reason", "origin", "notice", "product" ], "additionalProperties": false } }, "required": [ "id", "title", "detailedTitle", "brand", "mpn", "gtins", "productClass", "productType", "category", "locale", "textLocales", "country", "images", "badge", "highlights", "texts", "aiTexts", "prosCons", "review", "specs", "attributions", "profile", "completeness", "offers", "usedOffers", "linkOffers", "ebayOffers", "documents", "status", "activityState", "offersStatus", "updatedAt", "variantOf", "variantLabel", "variants", "lowestVariant", "isModel", "variantAxes", "priceRange", "replacement" ], "additionalProperties": false }, "Review": { "type": "object", "properties": { "scale": { "type": "string", "enum": [ "grade", "points10", "points100", "stars5" ] }, "score": { "type": "number" }, "best": { "type": "number" }, "worst": { "type": "number" }, "normalized": { "type": "number" }, "level": { "type": "integer", "minimum": 1, "maximum": 5 }, "verdict": { "type": "string" }, "scoreText": { "type": "string" }, "testedAt": { "nullable": true, "type": "string" }, "summary": { "nullable": true, "type": "string" }, "criteria": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number" }, "normalized": { "type": "number" }, "scoreText": { "type": "string" } }, "required": [ "name", "score", "normalized", "scoreText" ], "additionalProperties": false } }, "locale": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "scale", "score", "best", "worst", "normalized", "level", "verdict", "scoreText", "testedAt", "summary", "criteria", "locale", "updatedAt" ], "additionalProperties": false }, "SearchHit": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "image": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "bestPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "offerCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asin", "gtin", "mpn" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false } } }, "required": [ "id", "title", "brand", "productType", "image", "bestPrice", "offerCount", "status", "identifiers" ], "additionalProperties": false }, "SpecCompleteness": { "type": "object", "properties": { "filled": { "type": "integer" }, "required": { "type": "integer" }, "missing": { "type": "array", "items": { "type": "string" } } }, "required": [ "filled", "required", "missing" ], "additionalProperties": false }, "SpecItem": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "raw": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ] }, "unit": { "nullable": true, "type": "string" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] } }, "required": [ "key", "label", "value", "raw", "unit", "compare", "importance" ], "additionalProperties": false } }, "responses": { "BadRequest": { "description": "The request is invalid (missing or wrong parameters). Details are in `error.details`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig", "details": [ { "path": "ids", "message": "Ungültige Kennungen: abc" } ] } } } } }, "Unauthorized": { "description": "The key is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "Gültiger API-Key erforderlich" } } } } }, "PaymentRequired": { "description": "The account is suspended. Please check your plan and payment in the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "payment_required", "message": "Dein Konto ist gesperrt" } } } } }, "Forbidden": { "description": "The key lacks the permission for this route, or the website or API client is deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "forbidden", "message": "Dem API-Client fehlt die Berechtigung \"products:read\"" } } } } }, "NotFound": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "Produkt nicht gefunden" } } } } }, "TooManyRequests": { "description": "Too many requests. Try again after the time in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds after which you can try again", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen" } } } } } }, "parameters": { "AcBlog": { "name": "X-AC-Blog", "in": "header", "required": false, "description": "Only for site keys of WordPress networks: number of the subsite (`get_current_blog_id()`). Decides which tracking IDs go into the links. Invalid values are ignored.", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "AcBlogName": { "name": "X-AC-Blog-Name", "in": "header", "required": false, "description": "Name of the subsite, percent-encoded (UTF-8). Only together with `X-AC-Blog`.", "schema": { "type": "string", "maxLength": 200 } }, "AcBlogUrl": { "name": "X-AC-Blog-Url", "in": "header", "required": false, "description": "Address of the subsite, percent-encoded (UTF-8). Only together with `X-AC-Blog`.", "schema": { "type": "string", "maxLength": 500 } } }, "headers": { "RateLimitLimit": { "description": "Allowed requests per minute for this key", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests remaining in the current time window", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the current time window ends", "schema": { "type": "integer" } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ac_…", "description": "Key from your account (starts with `ac_`) in the header `Authorization: Bearer ac_…`. Site keys belong to a website, API clients to your own application." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative to `Authorization`: the same key in the header `X-API-Key`." } } } }