POST /v1/webhook/invalidate

Invalidate cached snapshots by path pattern so they are re-rendered on the next bot visit. Use this endpoint in deploy hooks, CMS webhooks, or any automation that needs to bust the snapshot cache after content changes. Matching snapshots are immediately marked stale and queued for background re-rendering.

How do I invalidate cached snapshots?

Send a POST request to /api/v1/webhook/invalidate with a JSON body containing your site ID and a path pattern. All snapshots matching the pattern are marked stale and automatically re-queued for rendering. Use this in deploy hooks for automatic cache busting whenever you ship new code or publish new content.

curl -X POST \
  -H "Authorization: Bearer ps_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"siteId": "site_abc123", "pattern": "/products/*"}' \
  https://search.perfectline.io/api/v1/webhook/invalidate

What is the request body?

The request body must be valid JSON with both siteId and pattern fields. The pattern supports wildcard matching to invalidate multiple snapshots in a single request.

Example request body:

{
  "siteId": "site_abc123",
  "pattern": "/products/*"
}

What wildcard patterns are supported?

The invalidation endpoint supports three types of path matching: exact paths, single- segment wildcards, and multi-segment wildcards. Patterns are matched against the full URL path of each cached snapshot. Use the most specific pattern possible to minimize unnecessary re-rendering work.

Single-segment wildcard (*): Matches exactly one path segment. /products/* matches /products/shoes but not /products/shoes/red.

Multi-segment wildcard (**): Matches one or more path segments. /products/** matches everything nested under /products/ at any depth.

Full-site wildcard (/**): Invalidates every cached snapshot for the site. Use this after major deploys when all pages may have changed.

What does the response look like?

A successful response returns HTTP 200 with a JSON body containing the count of snapshots that were invalidated (marked stale and queued for re-rendering). If the pattern matches zero snapshots, the count is 0 and no error is returned.

{
  "invalidated": 42
}

The invalidatedcount represents the number of unique snapshots that matched the pattern. Each invalidated snapshot is queued for re-rendering at normal priority. Invalidated snapshots remain serveable in a "stale" state until the re-render completes, ensuring bots never receive a 404 for previously-cached pages.

How do I use this with CI/CD?

Add an invalidation step to your deployment pipeline to automatically bust the snapshot cache after every deploy. Below is an example GitHub Actions workflow step that invalidates all snapshots after a successful Vercel deployment. For more complete examples including Netlify, Railway, and custom pipelines, see the CI/CD integration guide.

# .github/workflows/deploy.yml
name: Deploy and Invalidate

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Vercel
        run: vercel deploy --prod --token ${{ secrets.VERCEL_TOKEN }}

      - name: Invalidate PerfectSearch snapshots
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.PERFECTSEARCH_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"siteId": "${{ secrets.PERFECTSEARCH_SITE_ID }}", "pattern": "/**"}' \
            https://search.perfectline.io/api/v1/webhook/invalidate

For content-only updates (blog posts, product pages), use a specific pattern instead of /** to avoid re-rendering unchanged pages:

# Invalidate only blog posts after CMS publish
curl -X POST \
  -H "Authorization: Bearer ps_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"siteId": "site_abc123", "pattern": "/blog/**"}' \
  https://search.perfectline.io/api/v1/webhook/invalidate