What can I do with Prerender.io Rest API?

TL;DR

The Prerender.io REST API lets you control your prerendered cache from code instead of the dashboard. You can recache one URL or up to 1,000 at a time, search your cache, submit sitemaps, clear cache by URL pattern, and adjust how fast the render queue processes URLs. This means AI crawlers and search engines see updated content as soon as you push it, without waiting for cache expiration. API access is available on every Prerender.io plan.

 

How the API fits into your Prerender.io workflow

Prerender.io serves pre-rendered HTML snapshots to AI crawlers and search engines, which is what makes JavaScript-heavy sites indexable. The API extends that by giving you programmatic control over when and how content is refreshed in the cache. Instead of waiting for cache expiration, you can trigger a recache the moment a page changes, so crawlers always see your current content. The same applies to clearing stale pages, submitting new URLs from a sitemap, and tuning the render queue to match your infrastructure capacity.

Swagger and V3

All of the endpoints documented below are also available via Swagger. The new V3 API endpoints are documented separately.

Prerender.io token

The location of the Prerender.io token has changed. You can find it under the Security and Access menu under Prerender Token.

 

---

Recache API

Use the Recache API to cache a URL for the first time, or to refresh a URL that is already cached. This is a POST request and the payload must be JSON, or the request will fail.

The Recache API is the best way to keep costs down on plans with shorter cache expiration: set a longer cache expiration globally and use Recache to refresh only the pages that change most often.

URL

https://api.prerender.io/recache

Params

{
    "prerenderToken": "YOUR_TOKEN",
    "url": "http://www.example.com/url/to/recache"
}

Example

curl -H "Content-Type: application/json" -d '{"prerenderToken": "YOUR_TOKEN", "url": "http://www.example.com/"}' https://api.prerender.io/recache

Recaching multiple URLs

A single Recache request can include up to 1,000 URLs. To recache more than one URL, change the url parameter to urls and pass an array.

Params

{
    "prerenderToken": "YOUR_TOKEN",
    "urls": [
        "http://www.example.com/url/to/recache",
        "http://www.example.com/url/to/recache2"
    ]
}

Example

curl -H "Content-Type: application/json" -d '{"prerenderToken": "YOUR_TOKEN", "urls": ["http://www.example.com/url/to/recache", "http://www.example.com/url/to/recache2"]}' https://api.prerender.io/recache

You can also use our Python script to cache or recache URLs in bulk from a text file or a sitemap URL. The script and its documentation are here: Automate URL caching with the Prerender.io recache script.

Recaching mobile pages

To recache the mobile version of a page, add "adaptiveType": "mobile" to the request body.

Params

{
    "prerenderToken": "YOUR_TOKEN",
    "url": "http://www.example.com/url/to/recache",
    "adaptiveType": "mobile"
}

Example

curl -H "Content-Type: application/json" -d '{"prerenderToken": "YOUR_TOKEN", "url": "http://www.example.com/", "adaptiveType": "mobile"}' https://api.prerender.io/recache

 

---

Search API

The Search API lets you search for cached URLs in your account and inspect their cache status.

URL

https://api.prerender.io/search

Params

{
    "prerenderToken": "YOUR_TOKEN",
    "query": "example.com/path",
    "exactMatch": "https://example.com/path",
    "start": 0,
    "adaptiveType": "desktop"
}

• query: performs a "contains" match. Optional.
• exactMatch: returns results where the URL is fully identical. Optional. If both query and exactMatch are present, only exactMatch is used.
• start: pagination offset. The search returns 200 URLs per page. To get the next page, set start to 200, then 400, and so on. Optional.
• adaptiveType: can be "mobile" or "desktop". If you have both versions of a page, you can filter by device this way. Optional.

 

---

Sitemap API

The Sitemap API lets you add new URLs to the cache by submitting a sitemap XML file. Existing URLs are not recached. Use the Recache API for that.

URL

https://api.prerender.io/sitemap

Params

{
    "prerenderToken": "YOUR_TOKEN",
    "url": "https://www.sitemaps.org/sitemap.xml"
}

Example

curl -H "Content-Type: application/json" -d '{"prerenderToken": "YOUR_TOKEN", "url": "https://www.sitemaps.org/sitemap.xml"}' https://api.prerender.io/sitemap

 

---

Cache Clear API

The Cache Clear API removes URLs from your cache, either entirely or by pattern. This endpoint is available on current plans. If you are on a legacy plan, you do not have access to this API and will need to reach out to us to clear your cache.

The call schedules a clear job. The job usually runs quickly, but how long it takes depends on the size of your cache. You can check the job status with the endpoint described below. Only one clear job can be scheduled per user at a time. This is a POST request with two parameters.

URL

https://api.prerender.io/cache-clear

Params

{
    "prerenderToken": "YOUR_TOKEN",
    "query": "https://example.com%"
}

• prerenderToken: your API token.
• query: inserted into a SQL-like condition. Use % and ? as wildcards.
• https://example.com%: appending % deletes every cached URL that starts with the string before %. In this example, every cached URL beginning with https://example.com will be deleted.

Example

curl -X POST -H "Content-Type: application/json" -d '{"prerenderToken": "YOUR_TOKEN", "query": "https://example.com%"}' https://api.prerender.io/cache-clear

Return values

200: Cache clear queued
403: Cache clear in progress

Check Cache Clear job status

This is a GET request. Append your API token to the URL.

URL

https://api.prerender.io/cache-clear-status

Example

curl https://api.prerender.io/cache-clear-status/YOUR_TOKEN

Return values

403: in progress
200: not queued

 

---

Change Recache Speed API

This endpoint lets you adjust the rendering speed of your Manual / API and Automatic rendering queues. You can set a custom speed or revert to the default automatic delay.

For background on how the queues work, see Rendering queues.

Adjusting recache speed may impact your service

Before increasing the recache speed, check in with your development and infrastructure teams. A higher request rate during rendering can overload your origin or affect production performance. Make sure your stack can handle the load before changing this.

URL

https://api.prerender.io/change-recache-speed

Method

This is a POST request. You provide your Prerender.io token in the request body.

Params

{
    "prerenderToken": "YOUR_TOKEN",
    "urlsPerHour": 18000
}

• prerenderToken: your Prerender.io token. You can find it under the Security and Access menu.
• urlsPerHour: the number of URLs to recache per hour. Use 0 for automatic delay, or any value between 3600 and 36000.

Example

curl -X POST -H "Content-Type: application/json" -d '{"prerenderToken": "YOUR_TOKEN", "urlsPerHour": 18000}' https://api.prerender.io/change-recache-speed

Response: automatic delay (urlsPerHour = 0)

{
    "success": true,
    "recacheMetrics": null,
    "isAutomaticDelay": true
}

Response: custom delay

{
    "success": true,
    "recacheMetrics": {
        "delayBetweenURLs": 10286,
        "num10Sec": 1,
        "num30Sec": 3,
        "num1Min": 6,
        "num10Min": 59,
        "num1Hour": 350,
        "num1Day": 8400
    },
    "isAutomaticDelay": false
}

The recacheMetrics object shows how many pages will be cached in various time windows, based on the speed you set.

Recache speed reference

36000 is the fastest recache speed and 18000 is roughly half that. 0 reverts to the default automatic delay.

 

Related articles

• Desktop vs. mobile rendering
• How to change the speed of the render queue
• How do I use the Prerender.io recache script to refresh multiple URLs?
• How to cache specific URLs
• Rendering queues