Warm URLs

Trigger an on-demand cache warm for a specific list of URLs. The response is 202 Accepted — the run is queued and processed asynchronously.

POST /v1/sites/{id}/warm

Requires scope: boosts:write

Path parameters

Parameter	Type	Required	Description
`id`	integer	Required	Site ID.

Body parameters

Parameter	Type	Required	Description
`urls`	array	Required	List of URLs to warm. All URLs must belong to the site's domain. Maximum 5,000 URLs per request.
`region`	array	Optional	Target regions: `fr`, `us`, `eu`, `as`. Defaults to `["fr"]`.
`variations`	object	Optional	`user_agents` (mobile, desktop, bot, ai_crawler) and `languages`. Each combination counts as one call per URL.

Example request

curl -X POST https://api.cache-boost.com/v1/sites/42/warm \
  -H "Authorization: Bearer cb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.example.com/", "https://www.example.com/about"], "region": ["fr", "us"]}'

Response

Returns 202 Accepted.

{
  "run_id": 91,
  "url_count": 2,
  "status": "pending"
}

The warm run is asynchronous. Use the returned run_id to poll GET /v1/runs/{id} for progress. The site must be validated before warming.

Errors

Code	Description
`401`	Missing or invalid API key.
`403`	Insufficient scope, access denied, or quota exceeded.
`404`	Site not found.
`409`	Site is not validated, or a warm run is already in progress.
`422`	Validation error — missing or invalid fields, or URLs outside the site's domain.