Saved
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
GET | |
POST | |
GET | |
PATCH | |
DELETE | |
POST | |
POST |
List all saved
List saved heatmaps for the project. A saved heatmap pins a page URL and a set of viewport widths, and (for type 'screenshot') renders the page so heatmap data can be overlaid on it.
Required API key scopes
heatmap:readQuery parameters
- created_byinteger
- limitintegerDefault:
100 - offsetintegerDefault:
0 - orderstring
- searchstring
- statusstring
- typestring
Example request
GET /api /projects /:project_id /savedExample response
Status 200
Create saved
Create a saved heatmap for a page URL. For type 'screenshot' (the default) this enqueues a headless render of the page at each target width; poll the saved heatmap or its content endpoint until status is 'completed'. Provide 'widths' to control which viewport widths are rendered.
Required API key scopes
heatmap:writeRequest parameters
- namestringnull
- urlstring
- data_urlstringnull
- widthsarray
- typeDefault:
screenshot - deletedboolean
- block_consent_modalsboolean
Response
Example request
POST /api /projects /:project_id /savedExample response
Status 201
Retrieve saved
Get a single saved heatmap by its short_id, including per-width render status.
Required API key scopes
heatmap:readPath parameters
- short_idstring
Response
Example request
GET /api /projects /:project_id /saved /:short_idExample response
Status 200
Update saved
Update a saved heatmap (e.g. rename, change widths, or soft-delete via 'deleted'). Changing the URL of a 'screenshot' heatmap triggers a re-render.
Required API key scopes
heatmap:writePath parameters
- short_idstring
Request parameters
- namestringnull
- urlstring
- data_urlstringnull
- widthsarray
- typeDefault:
screenshot - deletedboolean
- block_consent_modalsboolean
Response
Example request
PATCH /api /projects /:project_id /saved /:short_idExample response
Status 200
Delete saved
Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
Required API key scopes
heatmap:writePath parameters
- short_idstring
Example request
DELETE /api /projects /:project_id /saved /:short_idExample response
Status 405 No response body
Create saved regenerate
Re-run screenshot generation for a saved heatmap of type 'screenshot'. Clears existing renders and re-renders at every target width; status returns to 'processing'.
Required API key scopes
heatmap:writePath parameters
- short_idstring
Response
Example request
POST /api /projects /:project_id /saved /:short_id /regenerateExample response
Status 200
Status 400 Not a screenshot
Create saved prewarm
Speculatively render a screenshot for a page URL ahead of heatmap creation, so it's ready (or closer to ready) by the time the user reaches the generation screen. Renders a single preview width. Idempotent within a short window: returns the existing in-flight or completed prewarm render for the same URL and consent setting if one exists (200), otherwise starts a new one (201). The result is reused when a heatmap is later created for the same URL.
Required API key scopes
heatmap:writeRequest parameters
- urlstring
- block_consent_modalsbooleanDefault:
false
Response
Example request
POST /api /projects /:project_id /saved /prewarm