Tag cacheable origin responses with the Surrogate-Key header (space-separated list of logical keys, e.g., product-123 category-shoes); Fastly stores the association between these keys and cached objects without exposing the header to end clients
To purge all objects associated with a surrogate key, send a POST request to https://api.fastly.com/service/<service-id>/purge/<surrogate-key> with the Fastly-Key header containing your API token; this purge is near-instant and propagates globally within seconds
To purge multiple surrogate keys in one API call, use the bulk purge endpoint: POST to https://api.fastly.com/service/<service-id>/purge with a JSON body {'surrogate_keys': ['key1','key2']} and the same Fastly-Key header
To purge a single URL (by path), send POST https://api.fastly.com/purge/<host>/<path> with the Fastly-Key header; this is slower to set up for programmatic use — prefer surrogate key purges for content-type-level invalidation
Design your surrogate key taxonomy around content identity: use object IDs for precise invalidation, entity-type keys for broader sweeps (e.g., purge all product listings), and a global key for full-site purges during deployments
Rotate API tokens used for purging separately from tokens used for configuration changes; use a token scoped to purge only (Engineer role with purge scope) to limit blast radius of a compromised credential
Known gotchas
Surrogate-Key headers must be set on the origin response before Fastly caches the object — you cannot retroactively tag an already-cached object; a cache miss after tag addition will tag newly cached copies, but previously cached copies remain untagged until they expire
The Surrogate-Key header has no enforced size limit but very long headers (thousands of keys per response) can cause header size issues at the origin or Fastly edge; keep per-response key counts reasonable (under a few dozen)
Soft-purge (PURGE with Fastly-Soft-Purge: 1 header) marks objects as stale rather than removing them — stale objects are served while Fastly revalidates with the origin, preventing a thundering-herd on popular content; use soft purge for high-traffic content where momentary stale serving is acceptable
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp