--- title: Warmup v2 Request slug: fluid-adserver-api/warmup-v2-request docTags: createdAt: 2025-08-25T13:13:11.308Z --- { "id": "iLBvf5mHZMkimSqAyg0pU", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://localhost/v2/{publisherUUID}", "servers": [], "name": "Warmup v2 Request", "description": "

This endpoint expects a warmup request. Each ad unit must include at least one of the following inputs:

\n
    \n
  1. searchQuery
    2. \n
  2. categories
    3. \n
  3. products
    4. \n
\n

You can also provide multiple ad units in the adUnits array.

", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "publisherUUID", "type": "string", "description": "

The UUID of a publisher, this value is provided by Pentaleap during the integration process

" } ], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "", "customType": "Request", "schema": [ { "name": "user", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/User", "customType": "User", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "Unique identifier for the end user. The value can be session cookie or any authenticated user identifier.\nAt least one of id or loggedInId is required.\n", "minLength": 1, "maxLength": 128 }, { "name": "loggedInId", "kind": "optional", "type": "string", "description": "

[Optional] A persistent user ID for logged in users/customers.\nAt least one of id or loggedInId is required.

", "minLength": 1, "maxLength": 128 }, { "name": "additionalIds", "kind": "optional", "type": "map", "description": "

[Optional] optional publisher-provided IDs for reporting and analytics purposes

\n

Validation Rules:

\n", "example": "{\"partner_x_id\":\"id123\",\"partner_y_id\":\"id456\"}", "customType": "map", "schema": [] }, { "name": "ip", "kind": "optional", "type": "string", "description": "

The IP address of the user, this value is provided by the publisher.

", "maxLength": 60 }, { "name": "agent", "kind": "optional", "type": "string", "description": "

The user agent of the user, this value is provided by the publisher.

", "maxLength": 400 }, { "name": "region", "kind": "optional", "type": "string", "description": "Region of the user\n", "example": "066", "maxLength": 100 }, { "name": "operationFlags", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "noReporting", "kind": "optional", "type": "boolean", "description": "

Use for test traffic in pre-production. When true, indicates to the Demand Source that the request should not be logged and counted.

" } ] }, { "name": "limitedTracking", "kind": "optional", "type": "boolean", "description": "Specifies whether the user has chosen to limit tracking.\n" } ] }, { "name": "adUnits", "kind": "required", "type": "array", "description": "

Validation Rules:

\n", "modelRef": "#/components/schemas/AdUnit", "customType": "AdUnit[]", "schema": [ { "name": "adUnitId", "kind": "required", "type": "string", "description": "

Unique identifier for the ad unit. The value can be session cookie or any authenticated ad unit identifier.

\n

Validation Rules:

\n", "minLength": 1, "maxLength": 100 }, { "name": "searchQuery", "kind": "optional", "type": "string", "description": "

The search query that the user entered for the current request, this is valid for the search pages only.

", "maxLength": 400 }, { "name": "categories", "kind": "optional", "type": "object", "description": "At least one of current or additional is required.\n", "modelRef": "#/components/schemas/Category", "customType": "Category", "schema": [ { "name": "current", "kind": "optional", "type": "string", "nullable": true, "description": "

The current category of the user, this value is provided by the publisher.

\n

Validation Rules:

\n", "maxLength": 200 }, { "name": "additional", "kind": "optional", "type": "array", "description": "

Additional categories of the user, this value is provided by the publisher.

\n

Validation Rules:

\n", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] }, { "name": "products", "kind": "optional", "type": "array", "description": "

Products on the page (item or basket). This is valid for product-scoped ad units.

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/Product", "customType": "Product[]", "schema": [ { "name": "gtin", "kind": "optional", "type": "string", "description": "

Is typically the \"Global Trade Item Number\" but generally\na retailer's unique product identifier.

\n

Validation Rules:

\n", "example": "00000000000000", "minLength": 1, "maxLength": 128 }, { "name": "price", "kind": "optional", "type": "number", "description": "Product price. Must be greater than or equal to 0.\n", "minimum": 0 }, { "name": "quantity", "kind": "optional", "type": "integer", "description": "Product quantity. Must be greater than or equal to 0.\n", "minimum": 0 }, { "name": "availability", "kind": "optional", "type": "string", "description": "

Product availability. Must be one of in_stock or out_of_stock.

", "enum": [ "in_stock", "out_of_stock" ] } ] }, { "name": "excludedProducts", "kind": "optional", "type": "array", "description": "

List of product GTINs that will be filtered out from the warmup demand if returned by DSPs for the given request. This only applies to SPA (Sponsored Product Ads).

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/excludedProducts", "customType": "excludedProducts", "schema": [] } ] }, { "name": "adUnitContext", "kind": "optional", "type": "object", "description": "Global context configurations used for all ad units in the request.\nThis optional field provides shared contextual information that applies to every ad unit.\n", "modelRef": "#/components/schemas/AdUnitContext", "customType": "AdUnitContext", "schema": [ { "name": "pageNumber", "kind": "optional", "type": "integer", "description": "Page number must be between 1 and 100\n" }, { "name": "filters", "kind": "optional", "type": "map", "description": "

This field contains demand source specific filters. The demand source names used here must be agreed upon with Pentaleap.\nFilters are passed to the demand source as-is, so they must follow the correct representation expected by the demand source\nespecially in cases where a single filter is provided as a one-element array.

\n

Validation Rules:

\n", "example": "filters: {\n \"DSP_Name-1\":[\"filter1\", \"filter2\"],\n \"DSP_Name-2\":[\"filter1,filter2,filter3\"]\n}\n", "customType": "map", "schema": [] }, { "name": "excludedProducts", "kind": "optional", "type": "array", "description": "

List of product GTINs that will be filtered out from the warmup demand if returned by DSPs for the given request. This only applies to SPA (Sponsored Product Ads).

\n

Validation Rules:

\n
    \n
  • maxItems: 200
    • \n
", "modelRef": "#/components/schemas/excludedProducts", "customType": "excludedProducts", "schema": [] } ] } ], "modelRef": "#/components/schemas/Request", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Request Successful and data is already processed", "jsonExample": "", "isExpanded": true }, { "statusCode": "202", "description": "Request Accepted and will be processed asynchronously", "jsonExample": "", "isExpanded": true }, { "statusCode": "400", "description": "One or more request parameters don't comply to the API specifications.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "errors", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "MHyic2lHZ6AHUPnqxZFrs", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://localhost/v2/{publisherUUID} \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"user\": {},\n \"adUnits\": [\n {\n \"adUnitId\": \"\"\n }\n ]\n }'" }, { "id": "Gkl7P8l_bh9ZjZ-rqsR6K", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"user\": {},\n \"adUnits\": [\n {\n \"adUnitId\": \"\"\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://localhost/v2/{publisherUUID}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "9dWQ9TwfRymy8fG4g-uhM", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://localhost/v2/{publisherUUID}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"user\": {},\n \"adUnits\": [\n {\n \"adUnitId\": \"\"\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "DwBLaNcGsfMFMF1MzeuoU", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://localhost/v2/{publisherUUID}\"\n\npayload = json.dumps({\n \"user\": {},\n \"adUnits\": [\n {\n \"adUnitId\": \"\"\n }\n ]\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "MHyic2lHZ6AHUPnqxZFrs" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Request Successful and data is already processed\n" }, { "id": "response-1-202", "language": "202", "code": "// Request Accepted and will be processed asynchronously\n" }, { "id": "response-2-400", "language": "400", "code": "// One or more request parameters don't comply to the API specifications.\n{\n \"errors\": [\n \"\"\n ]\n}" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }