Skip to main content

Purging cache via the API

Purging clears cached content so the next visitor gets fresh bytes from your origin. This guide is task-focused; the exact request/response contract lives in the API reference. All examples authenticate with an API key in the X-API-Key header.

How purge works (read this first)​

A purge is asynchronous. The API enqueues the work and responds 200 immediately with a job count — that means the jobs were queued, not that the cache has already cleared. The background worker then applies the purge to every active hostname, across all Origin Shields first and then all healthy PoP nodes.

200 means queued, not cleared

A 200 response with a jobCount confirms the purge was accepted and queued. It is fire-and-forget — there is no callback or status to confirm the cache actually cleared. Allow a short propagation window before re-testing.

Single purge​

POST /api/property/{id}/purge

Body:

{ "type": "All", "value": null, "matchType": null }

Purge types​

typeMeaningvalue
AllPurge everything for the propertyOmitted / ignored
ExtensionPurge files with a given extensionRequired (for example jpg)
PathPurge a specific pathRequired (for example /images/logo.png)
RegexPurge by patternRequired (the pattern)

type is required and case-insensitive. There is no separate wildcard or tag field — wildcard-style purging is done with type: "Regex".

Match type (Regex only)​

matchType is honored only when type is Regex. For Extension and Path it is ignored.

matchTypeBehavior
equalsExact match
containsSubstring match
starts_withPrefix match
ends_withSuffix match
regexRegular-expression match (default when omitted or blank)

Examples​

Purge everything:

curl -X POST https://api.paradarum.com/api/property/123/purge \
  -H "X-API-Key: pdm_YOUR_RAW_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "type": "All" }'

Purge a single path:

curl -X POST https://api.paradarum.com/api/property/123/purge \
  -H "X-API-Key: pdm_YOUR_RAW_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "type": "Path", "value": "/images/logo.png" }'

Purge by extension:

curl -X POST https://api.paradarum.com/api/property/123/purge \
  -H "X-API-Key: pdm_YOUR_RAW_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "type": "Extension", "value": "jpg" }'

Purge by pattern with a match type:

curl -X POST https://api.paradarum.com/api/property/123/purge \
  -H "X-API-Key: pdm_YOUR_RAW_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "type": "Regex", "value": "/blog/", "matchType": "starts_with" }'

Success response​

{
  "succeeded": true,
  "message": "Purge request accepted. 12 jobs queued across 2 shields + 4 PoPs.",
  "data": { "jobCount": 12, "shields": 2, "nodes": 4, "hostnames": 1 }
}

Batch purge​

Combine several instructions into one round-trip.

POST /api/property/{id}/purge/batch
curl -X POST https://api.paradarum.com/api/property/123/purge/batch \
  -H "X-API-Key: pdm_YOUR_RAW_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
        "items": [
          { "type": "All" },
          { "type": "Path", "value": "/index.html" },
          { "type": "Extension", "value": "css" },
          { "type": "Regex", "value": "^/assets/", "matchType": "regex" }
        ]
      }'

Each item has the same shape as a single purge and is validated independently. Valid items are queued; invalid ones are reported back in rejected, each with its index and a reason.

{
  "succeeded": true,
  "message": "...",
  "data": {
    "jobCount": 12,
    "accepted": 3,
    "rejected": [{ "index": 1, "reason": "Value is required..." }],
    "shields": 2,
    "nodes": 4,
    "hostnames": 1
  }
}
One bad item does not fail the batch

A single invalid item never fails the whole request — it lands in rejected[] while the valid items proceed. The batch only returns 400 when every item is invalid (or the items array is empty).

Guards and error responses​

A purge can be blocked before anything is queued. Branch on the HTTP status and read the message.

StatusWhen it happensExample message
400Missing/invalid type or value; empty batch; no active hostnamesNo active hostnames found for this property.
403Property is disabled or suspendedThis property is currently {status}... Configuration changes are not allowed until it is re-enabled.
404Property not found, or owned by another accountProperty not found.
500No healthy, traffic-enabled PoP nodes availableNo active cache nodes found.
Requirements for a purge to queue

The property must have at least one Active hostname (otherwise 400) and at least one healthy PoP node (otherwise 500). A disabled or suspended property rejects purges with 403.

Automate from WordPress or PrestaShop​

CMS purge plugins call these same endpoints — typically purge after a single post or product changes, and purge/batch to clear several paths at once.

Paradarum ships official, ready-to-install plugins that do exactly this for you — no code required:

Use a dedicated key per site

Create a separate, descriptively named API key for each site (for example Production WordPress). If a site is decommissioned or a key leaks, revoke just that key without disrupting your other integrations.