Create a boost

Create a new cache warming campaign.

POST /v1/boosts

Requires scope: boosts:write

Body parameters

Parameter	Type	Required	Description
`name`	string	Required	Display name for the boost.
`site_id`	integer	Required	ID of the site to warm.
`source_type`	string	Required	`sitemap` or `csv`.
`region`	array	Required	Target regions. Values: `fr`, `us`, `eu`, `as`.
`sitemap_ids`	array	Optional	Required when `source_type` is `sitemap`. IDs of sitemaps to warm.
`source_url`	string	Optional	CSV file URL. Required when `source_type` is `csv`.
`url_root`	string	Optional	Only warm URLs starting with this path. Default: `/`.
`exclude_ext`	array	Optional	File extensions to skip (e.g. `jpg`, `png`, `css`, `js`).
`variations`	object	Optional	Warming variations with `user_agents` (mobile, desktop, bot, ai_crawler) and `languages` (e.g. fr-FR, en-US). Each combination counts as one call per URL.
`schedule`	string	Optional	Cron expression (UTC) for automatic scheduling.
`call_limit`	integer	Optional	Maximum number of calls for this boost.
`ignore_errors`	boolean	Optional	If `true`, the boost will not auto-pause on high error rates. Default: `false`.
`report_email_enabled`	boolean	Optional	Send an email report when a run completes. Default: `true`.

Example request

curl -X POST https://api.cache-boost.com/v1/boosts \
  -H "Authorization: Bearer cb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily warm",
    "site_id": 42,
    "source_type": "sitemap",
    "region": ["fr"],
    "sitemap_ids": [7],
    "schedule": "0 1 * * *"
  }'

Response

Returns 201 Created with the full boost object.

{
  "id": 15,
  "site_id": 42,
  "name": "Daily warm",
  "status": "pending",
  "source_type": "sitemap",
  "region": ["fr"],
  "sitemap_ids": [7],
  "url_root": "/",
  "exclude_ext": null,
  "variations": null,
  "content_types": null,
  "ignore_errors": false,
  "report_email_enabled": true,
  "schedule": "0 1 * * *",
  "next_run_at": "2025-01-16T01:00:00Z",
  "call_limit": null,
  "created_at": "2025-01-15T10:30:00Z"
}

Errors

Code	Description
`401`	Missing or invalid API key.
`403`	Insufficient scope or access denied.
`404`	Site or sitemap not found.
`422`	Validation error — missing or invalid fields.