Skip to main content

Origin Shield

Origin Shield is a central cache layer that sits between the edge PoPs and your real origin. With a shield enabled, cache misses from many PoPs collapse onto one shield node instead of all hitting your origin directly — reducing origin load and improving cache efficiency.

How it works​

Without a shield, every PoP that gets a cache miss fetches from your origin. With a shield, those misses go to the shield first; only the shield reaches back to your origin. Fewer, deduplicated requests reach your backend.

Enabling a shield​

  1. Open your property, go to the General tab, and scroll to the Origin Shield card.
  2. Toggle it on. A Shield Server dropdown appears, populated from the active shields list.
  3. Choose one of:
    • Default (PoP configured) — uses the PoP's own default shield. Stored as shield_id: null.
    • A named shield, shown as Name (Region · Location).
  4. Click Save on the card.
tip

Pick a shield close to your origin's region for the best performance — the shield-to-origin hop is the one that benefits most from low latency.

Where it's stored​

The shield assignment is persisted into the property's general-settings JSON under origin_shield:

{
  "origin_shield": {
    "enabled": true,
    "shield_id": 3
  }
}

PUT this (as part of the full general-settings object) to https://api.paradarum.com/api/property/{id}/general-settings?accountId={accountId}.

FieldTypeMeaning
enabledbooleanWhether the shield is on.
shield_idint | nullA specific shield, or null for the PoP default.

:::info Two ways to "not pick a shield" shield_id: null with enabled: true means use the PoP's default shield. That is different from enabled: false, which turns the shield off entirely. :::

Changing or disabling a shield triggers a purge​

When you change or disable a previously selected shield, the API automatically enqueues a purge-all job on the previously assigned shield, for every hostname of the property. This clears stale content off the old shield so visitors aren't served outdated responses.

warning

This purge only fires if the previous settings had origin_shield.enabled set to true. Switching shields is therefore safe — the old one is flushed automatically — but expect a brief cache-warming period on the new shield.

Choosing from available shields​

Regular users get a read-only list of active shields to populate the dropdown:

curl "https://api.paradarum.com/api/origin-shields" \
  -H "X-API-Key: pdm_YOUR_KEY"
{
  "message": "Origin shields retrieved",
  "succeeded": true,
  "data": [
    { "id": 3, "name": "Shield EU", "region": "EU", "location": "DE", "provider": "Hetzner Cloud" }
  ]
}

The list returns active shields only, ordered by region then name.

:::note Creating shields is admin-only End users never create shields — they only enable one and pick from the active list. Provisioning and managing shields (their IPs, region, health, scheme, and port) is handled by Paradarum operators. :::