Purge and prefetch cache-jobs
Purge cached URLs or directories, and prefetch given URLs.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/cache-jobsList purge/prefetch jobs
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
type | string | Only list jobs of this type. |
url | string | If it starts with http:// or https://, exact match on the full URL, normalized as on submission (the job's URL list contains it); otherwise exact match on the host name. |
/api/v2/cache-jobsCreate purge/prefetch job
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
typeRequired | string | purge_url = purge URLs; purge_dir = purge directories (URL ends with /); prefetch = prefetch. |
urlsRequired | string[] | http(s)://host/path (normalized, see create); at most 100 entries per prefetch. |
/api/v2/cache-jobs/{id}Get purge/prefetch job
Authentication: User (some parameters admin only)
Purge and prefetch object
| Field | Type | Description |
|---|---|---|
batches | integer | How many push tasks this submission was split into (prefetch is split by node timeout; purge is always 1). id, urls, status, progress, regions and results are the merged values of all batches of the submission. |
by_admin | boolean | Whether an administrator submitted the job on the tenant's behalf (true means it does not count toward the tenant's daily quota); false when the tenant submitted it. |
created_at | string | Created at |
id | integer | Record ID |
progress | CacheJobProgress | Progress of the job across all nodes (read-only, counts only). total = nodes that have reported + in-use nodes that have not yet reported (while the job is running); once the job ends only nodes that reported are counted. |
regions | CacheJobRegion[] | Node progress summarized by region (returned in details only), in descending order of total; nodes without a region are grouped as "Unassigned". Same shape for tenants and administrators; counts only, never node names, IPs or node IDs. |
results | CacheJobNodeResult[] | Execution result of each node (returned in details only; only administrators see nodes, for tenants this is always an empty array, use progress and regions instead). |
site_id | integer | Site ID |
status | string | Status of the push task (if some nodes fail it stays pending and retries with backoff, then becomes failed when retries run out). With several batches, any failed batch makes it failed; otherwise it is running/pending until every batch is done. |
tenant_id | integer | Owner tenant (user) ID |
tenant_name | string | Display name of the tenant that owns the job; tenants calling it see their own name; omitted when the tenant has been deleted. |
type | string | purge_url = purge URLs; purge_dir = purge directories (URL ends with /); prefetch = prefetch. |
updated_at | string | Updated at |
urls | string[] | http(s)://host/path (normalized, see create); at most 100 entries per prefetch. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}