Version 2.4.8 · latest

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.

CacheAuthentication: User (some parameters admin only)3 endpoints

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.

GET/api/v2/cache-jobsList purge/prefetch jobs

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
typestring Only list jobs of this type.
Values ["purge_url","purge_dir","prefetch"]
urlstring 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.
POST/api/v2/cache-jobsCreate purge/prefetch job

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
typeRequiredstring purge_url = purge URLs; purge_dir = purge directories (URL ends with /); prefetch = prefetch.
Values ["purge_url","purge_dir","prefetch"]
urlsRequiredstring[] http(s)://host/path (normalized, see create); at most 100 entries per prefetch.
GET/api/v2/cache-jobs/{id}Get purge/prefetch job

Authentication: User (some parameters admin only)

Purge and prefetch object

FieldTypeDescription
batchesinteger 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.
read-only
by_adminboolean 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.
read-only
created_atstring Created at
read-only
idinteger Record ID
read-only
progressCacheJobProgress 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.
read-only
regionsCacheJobRegion[] 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.
read-only
resultsCacheJobNodeResult[] 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).
read-only
site_idinteger Site ID
read-only
statusstring 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.
read-onlyValues ["pending","running","done","failed"]
tenant_idinteger Owner tenant (user) ID
read-only
tenant_namestring Display name of the tenant that owns the job; tenants calling it see their own name; omitted when the tenant has been deleted.
read-only
typestring purge_url = purge URLs; purge_dir = purge directories (URL ends with /); prefetch = prefetch.
Values ["purge_url","purge_dir","prefetch"]
updated_atstring Updated at
read-only
urlsstring[] 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.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "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"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command