Encited

Cache Invalidation

Encited serves crawlers a stored snapshot of each page. When you change a page, its snapshot keeps the old content until the page is rendered again. Use these endpoints to render pages again right away, or to remove the snapshots of pages you took down.

When you want to Use
Refresh one page after you edit it Invalidate Single Page
Refresh a list of pages Invalidate Multiple Paths
Refresh every page in your sitemap Invalidate Entire Site
Refresh only the pages whose sitemap lastmod changed Invalidate Updated Paths
Stop serving pages you took down or made private Remove Paths
Remove the snapshots of pages your sitemap no longer lists, or of the whole site Remove Site Snapshots

The invalidate endpoints only refresh. They never delete a snapshot.

A site renders a fixed number of pages at the same time, so many small calls do not finish sooner than a few full ones. See Limits before you send a large number of pages.

How a refresh works#

The page keeps serving its current snapshot until the new render replaces it, so it is never left without one. Cached copies in some locations can serve the old version for up to 5 minutes.

The render runs in the background, and the response returns a status, not HTML. To get the rendered HTML in the same request, call the Render API with cache_invalidate=1.

If nothing could be queued, the response is still HTTP 200, with ok: false and an error code: render_limit_reached, origin_not_reachable, origin_host_not_reachable or path_not_reachable. So check ok, and do not rely on the status code alone.

A call that goes over one of the limits is different: it gets a 400 or 429 status with an error code, and nothing is queued.

Limits#

A site renders a fixed number of pages at the same time. Each call to an invalidate endpoint makes one render job, and each job takes a share of that capacity, however few pages it has. A call with 5 pages takes the same share as a full call.

So put as many pages as you can in each call. A list of pages sent in a few full calls finishes much sooner than the same pages sent one per call.

Limit Value Applies to Response over the limit
Paths per call 200 invalidate-paths-cache only 400 with too_many_paths
Unfinished render jobs per site 100 All four invalidate endpoints 429 with too_many_open_jobs and a Retry-After header
Invalidate calls per site 60 per minute All four invalidate endpoints 429 with rate_limited and a Retry-After header

The limits are per site. All API keys of the site, and the dashboard, share them.

Paths per call#

This limit is for invalidate-paths-cache only. Its paths array takes 1 to 200 paths in one call. Duplicates are dropped before the count. A longer list is refused, and no page is queued:

{ "error": "too_many_paths" }

Split a longer list into calls of 200. To refresh a whole site, use invalidate-site-cache, which has no such limit.

Delayed renders#

When the site is already rendering at its full capacity, a call is still accepted. Its pages wait their turn. The response says so:

{
  "ok": true,
  "prewarmed": 12,
  "delayed": true,
  "message": "This site has no free render task, so these pages wait their turn. To finish sooner, send many pages in one call (up to 200 paths), not one call per page. Details: https://encited.com/docs/api-reference/cache-invalidation#delayed-renders"
}

You do not need to send the call again. The pages render when the site has capacity, and each page keeps serving its current snapshot until then.

delayed is false when the pages start at once. invalidate-site-cache and invalidate-updated-paths do not return delayed, because they find their pages in the background.

If you see delayed: true often, your calls are too small or too many. Put more pages in each call.

Open job limit#

A render job is unfinished while any of its pages waits or renders. When a site has 100 unfinished jobs, a new call to any invalidate endpoint is refused with HTTP 429, and nothing is queued:

{
  "error": "too_many_open_jobs",
  "message": "This site has 100 re-render jobs that are not finished. Wait for the number of seconds in the Retry-After header, then send the call again. Details: https://encited.com/docs/api-reference/cache-invalidation#open-job-limit"
}

The Retry-After header gives the number of seconds to wait. After that time, send the same call again. It can be refused again when the site is still full, so repeat until it is accepted.

The MCP tools rerender_pages and rerender_site follow the same limit. They return the too_many_open_jobs error with this text: "This site has too many re-render jobs that are not finished. Wait a few minutes, then retry. Details: https://encited.com/docs/api-reference/cache-invalidation#open-job-limit"

Rate limit#

A site takes at most 60 invalidate calls per minute. A call above that is refused with HTTP 429 and a Retry-After header:

{ "error": "rate_limited" }

Handle a 429#

async function invalidatePaths(domain, paths) {
  for (;;) {
    const response = await fetch(
      'https://encited.com/api/prerender/cache/invalidate-paths-cache',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-lovablehtml-api-key': '<API_KEY>'
        },
        body: JSON.stringify({ domain, paths })
      }
    );
    if (response.status !== 429) return response.json();
    const seconds = Number(response.headers.get('Retry-After')) || 60;
    // A few random seconds stop many waiting calls from returning together.
    const jitterMs = Math.random() * 5000;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000 + jitterMs));
  }
}

// Send a long list in calls of 200, one after the other.
for (let i = 0; i < allPaths.length; i += 200) {
  await invalidatePaths('your-app.com', allPaths.slice(i, i + 200));
}

Invalidate Single Page#

POST /api/prerender/cache/invalidate-page-cache#

Re-render the snapshot for a single page path.

Request Body#

Parameter Type Description
domain (required) string Domain name (e.g., "your-app.com")
path (required) string Page path to re-render (e.g., "/pricing")

Response Body#

delayed is true when the page waits its turn. See Delayed renders.

{
  "ok": true,
  "prewarmed": 1,
  "delayed": false
}

Example#

const response = await fetch(
  'https://encited.com/api/prerender/cache/invalidate-page-cache',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-lovablehtml-api-key': '<API_KEY>'
    },
    body: JSON.stringify({
      domain: 'your-app.com',
      path: '/pricing'
    })
  }
);

const result = await response.json();
// { "ok": true, "prewarmed": 1, "delayed": false }
curl -X POST \
  "https://encited.com/api/prerender/cache/invalidate-page-cache" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{"domain":"your-app.com","path":"/pricing"}'

Invalidate Multiple Paths#

POST /api/prerender/cache/invalidate-paths-cache#

Re-render the snapshots for several page paths in one request. One call takes at most 200 paths.

Request Body#

Parameter Type Description
domain (required) string Domain name
paths (required) string[] Paths to re-render, 1 to 200. Duplicates are dropped. See Paths per call.

Response Body#

prewarmed is the number of pages queued. It can be lower than the number of paths you sent when your render allowance cuts the list short. delayed is true when the pages wait their turn. See Delayed renders.

{
  "ok": true,
  "prewarmed": 3,
  "delayed": false
}

Example#

const response = await fetch(
  'https://encited.com/api/prerender/cache/invalidate-paths-cache',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-lovablehtml-api-key': '<API_KEY>'
    },
    body: JSON.stringify({
      domain: 'your-app.com',
      paths: ['/', '/pricing', '/blog/post']
    })
  }
);

const result = await response.json();
// { "ok": true, "prewarmed": 3, "delayed": false }
curl -X POST \
  "https://encited.com/api/prerender/cache/invalidate-paths-cache" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{"domain":"your-app.com","paths":["/","/pricing","/blog/post"]}'

Invalidate Entire Site#

POST /api/prerender/cache/invalidate-site-cache#

Re-render every page in a domain's sitemap. Use sparingly.

Request Body#

Parameter Type Description
domain (required) string Domain name
sitemapUrl string (URL) Custom sitemap URL for path discovery. Falls back to the domain's stored sitemap if omitted.

This queues a render for every page in your sitemap, and each one counts against your render usage.

The work runs in the background. batchGroupId identifies the batch.

One call counts as one job toward the open job limit, however many pages the site has. So use this endpoint for a full refresh, not many calls to invalidate-paths-cache. The rate limit applies to this call too.

Response Body#

{
  "ok": true,
  "accepted": true,
  "batchGroupId": "bg_01J8..."
}

Example#

const response = await fetch(
  'https://encited.com/api/prerender/cache/invalidate-site-cache',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-lovablehtml-api-key': '<API_KEY>'
    },
    body: JSON.stringify({
      domain: 'your-app.com',
      sitemapUrl: 'https://your-app.com/sitemap.xml'
    })
  }
);

const result = await response.json();
// { "ok": true, "accepted": true, "batchGroupId": "bg_01J8..." }
curl -X POST \
  "https://encited.com/api/prerender/cache/invalidate-site-cache" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{"domain":"your-app.com"}'

Invalidate Updated Paths#

POST /api/prerender/cache/invalidate-updated-paths#

Re-render only the pages whose sitemap lastmod is newer than the cached snapshot.

Request Body#

Parameter Type Description
domain (required) string Domain name (e.g., "your-app.com")
sitemapUrl string (URL) Custom sitemap URL. Falls back to the domain's stored sitemap if omitted.

A path is considered "updated" if its sitemap <lastmod> date is more recent than the cached snapshot's creation time, or if the path has never been cached. Paths without a <lastmod> entry are always included.

The open job limit and the rate limit apply to this call too.

Response Body#

{
  "ok": true,
  "accepted": true,
  "batchGroupId": "bg_01J8..."
}

Example#

const response = await fetch(
  'https://encited.com/api/prerender/cache/invalidate-updated-paths',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-lovablehtml-api-key': '<API_KEY>'
    },
    body: JSON.stringify({
      domain: 'your-app.com',
      sitemapUrl: 'https://your-app.com/sitemap.xml'
    })
  }
);

const result = await response.json();
// { "ok": true, "accepted": true, "batchGroupId": "bg_01J8..." }
curl -X POST \
  "https://encited.com/api/prerender/cache/invalidate-updated-paths" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{"domain":"your-app.com"}'

Remove Paths#

POST /api/prerender/cache/purge-paths#

Remove the snapshots of specific page paths. Removal does not render and does not count against your render usage.

After removal, the next crawler visit renders the page again when On-demand render is on for the site. When it is off, the crawler gets the page from your server. A scheduled refresh can also render it again, for example while your sitemap still lists it. A render that gets an error status from your server, such as 404 or 410, stores nothing.

Request Body#

Parameter Type Description
domain (required) string Domain name (e.g., "your-app.com")
paths (required) string[] Paths whose snapshots to remove, 1 to 500. Duplicates are dropped.

Response Body#

deleted is the number of snapshots removed. A path with no snapshot is skipped.

{
  "deleted": 2
}

Example#

curl -X POST \
  "https://encited.com/api/prerender/cache/purge-paths" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{"domain":"your-app.com","paths":["/old-page","/blog/removed-post"]}'

Remove Site Snapshots#

POST /api/prerender/cache/purge-site#

Remove snapshots across the whole site.

Request Body#

Parameter Type Description
domain (required) string Domain name
keep (required) "sitemap" or "none" "sitemap" removes every snapshot whose page your sitemap no longer lists. "none" removes every snapshot of the site.
cursor string The cursor from the previous response, to continue a large removal

One call removes up to 50,000 snapshots. When more remain, the response has a cursor. Call again with that cursor until it is null.

Response Body#

{
  "ok": true,
  "deleted": 50000,
  "cursor": "..."
}

When nothing is removed for one of the reasons below, the response is still HTTP 200, with ok: false and an error code. Check ok, not the status code.

Error code Meaning
sitemap_not_found keep: "sitemap" needs a sitemap, and this domain has none. Set one, or use purge-paths
sitemap_too_large The sitemap lists more than 250,000 pages, or it was cut short while read, so it cannot be trusted as the list of live pages. Use purge-paths
origin_shared Another connected domain renders through the same origin, so a sitemap filter would remove its pages. Use purge-paths

Example#

let cursor;
let deleted = 0;
do {
  const response = await fetch(
    'https://encited.com/api/prerender/cache/purge-site',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-lovablehtml-api-key': '<API_KEY>'
      },
      body: JSON.stringify({ domain: 'your-app.com', keep: 'sitemap', cursor })
    }
  );
  const result = await response.json();
  if (!result.ok) throw new Error(result.error);
  deleted += result.deleted;
  cursor = result.cursor ?? undefined;
} while (cursor);
curl -X POST \
  "https://encited.com/api/prerender/cache/purge-site" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{"domain":"your-app.com","keep":"sitemap"}'