GET /v1/snapshot

Retrieve a pre-rendered snapshot of any page on your site. The snapshot endpoint is the primary read path used by the middleware and DNS proxy to serve bot traffic. You can also call it directly to inspect cached content or build custom integrations.

How do I fetch a snapshot?

Send a GET request to /api/v1/snapshot with your site ID, the page path, and an optional format parameter. The API returns the pre-rendered content along with rendering metadata including timestamps and cache status. Include your API key in the Authorization header as a Bearer token.

bash

curl -H "Authorization: Bearer ps_live_abc123def456" \
  "https://search.perfectline.io/api/v1/snapshot?site_id=site_abc123&path=/products/shoes&format=html"

The response includes the full rendered content and metadata about when the snapshot was created and when it will become stale.

What are the query parameters?

All parameters are passed as query string parameters on the GET request. The site_id and path parameters are required. The format parameter controls the output format and defaults to HTML if omitted.

Parameter	Type	Required	Description
site_id	string	Required	Your site ID, found on the site overview page in the PerfectSearch dashboard.
path	string	Required	The URL path to fetch a snapshot for, e.g. /products/shoes. Must start with a forward slash.
format	string	Default: html	The output format for the snapshot content. Accepted values: html, markdown, or auto.

What does the response look like?

A successful response returns HTTP 200 with a JSON body containing the rendered content, rendering timestamps, and cache status. The renderedAt timestamp shows when the snapshot was last generated by the rendering worker. The staleAt timestamp indicates when the snapshot will be considered stale and eligible for re-rendering.

json

{
  "siteId": "site_abc123",
  "path": "/products/shoes",
  "format": "html",
  "content": "<!DOCTYPE html><html lang=\"en\"><head><title>Running Shoes | Acme Store</title><meta name=\"description\" content=\"Premium running shoes for every terrain.\"></head><body><main><h1>Running Shoes</h1><p>Explore our collection of premium running shoes...</p></main></body></html>",
  "renderedAt": "2026-02-20T10:30:00Z",
  "staleAt": "2026-02-21T10:30:00Z",
  "status": "fresh"
}

When requesting Markdown format, the content field contains clean Markdown instead of HTML:

json

{
  "siteId": "site_abc123",
  "path": "/products/shoes",
  "format": "markdown",
  "content": "# Running Shoes\n\nExplore our collection of premium running shoes designed for every terrain.\n\n## Featured Models\n\n- **TrailBlazer Pro** - $149.99\n- **CloudStep Ultra** - $129.99\n- **SpeedLite 3** - $99.99",
  "renderedAt": "2026-02-20T10:30:00Z",
  "staleAt": "2026-02-21T10:30:00Z",
  "status": "fresh"
}

What status codes can this endpoint return?

The snapshot endpoint returns standard HTTP status codes. A 200 response means a snapshot was found and returned, while a 404 means no snapshot exists yet for that path. When a 404 is returned, PerfectSearch automatically queues a crawl job to render the page, so a subsequent request will return the snapshot once rendering completes.

Status	Meaning	Details
200	Snapshot found	Content returned with rendering metadata. Check the `status` field for cache freshness.
404	No snapshot	No snapshot exists for this path. A crawl job has been automatically queued. Retry in 10–30 seconds.
401	Unauthorized	Missing or invalid API key in the Authorization header.
429	Rate limited	Too many requests. Wait for the number of seconds specified in the `Retry-After` response header.

Stale-while-revalidate behavior: If a snapshot exists but has passed its staleAt timestamp, the API returns HTTP 200 with "status": "stale" and simultaneously queues a background re-render. This ensures bots always receive content immediately rather than waiting for a fresh render. The next request after re-rendering completes will return the updated snapshot with "status": "fresh".

What does auto format detection do?

When you set format=auto, PerfectSearch inspects the User-Agent of the original bot request to determine the optimal content format. LLM and AI bots receive clean Markdown that is optimized for ingestion into language models, while traditional search engine crawlers receive fully-rendered HTML with complete meta tags and structured data.

Bot User-Agent	Detected As	Format Served
Googlebot	Search engine	HTML
Bingbot	Search engine	HTML
ChatGPT-User	LLM bot	Markdown
ClaudeBot	LLM bot	Markdown
PerplexityBot	LLM bot	Markdown
Applebot	Search engine	HTML

When using the middleware or DNS proxy, the User-Agent is automatically forwarded from the original request. When calling the API directly, auto format detection uses the User-Agent of your API request, so you should pass format=html or format=markdown explicitly instead.

Format override per site

You can override the auto-detection behavior per site in the PerfectSearch dashboard under Settings → Snapshot Format. Set it to "Always HTML" or "Always Markdown" if you want consistent output regardless of bot type.