API Overview

The PerfectSearch REST API lets you fetch pre-rendered snapshots, queue pages for rendering, and invalidate cached content programmatically. All endpoints follow consistent authentication, error handling, and rate limiting conventions documented below.

How do I authenticate API requests?

Every API request must include a Bearer token in the Authorizationheader. Your API key is available in the PerfectSearch dashboard under your site's Settings page. API keys are prefixed with ps_live_ for production and ps_test_ for test environments. Include the key in every request exactly as shown below.

bash

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

Navigate to Dashboard → your site → Settings → API Key to find or regenerate your key. Regenerating a key immediately invalidates the previous one.

What is the base URL?

All API endpoints are served from a single base URL. Append the endpoint path to this base URL for every request. The API is versioned in the URL path — the current and only version is v1. There is no separate staging URL; use test-mode API keys for non-production requests.

text

https://search.perfectline.io/api/v1

Full endpoint URLs:

GET https://search.perfectline.io/api/v1/snapshot — Fetch a snapshot
POST https://search.perfectline.io/api/v1/snapshot/queue — Queue pages for rendering
POST https://search.perfectline.io/api/v1/webhook/invalidate — Invalidate cached snapshots

What are the rate limits?

Rate limits are enforced per API key on a sliding one-minute window. The limit depends on your plan tier. When you exceed the limit, the API responds with HTTP 429 and includes a Retry-After header indicating how many seconds to wait before retrying. Rate limit headers are included in every successful response so you can monitor your usage proactively.

Plan	Requests / minute
Trial	100
Starter	100
Growth	2,000
Scale	10,000

Rate limit response headers included in every response:

text

X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1994
X-RateLimit-Reset: 1709312460

What do error responses look like?

All error responses return a JSON body with a single error field containing a human-readable message. The HTTP status code indicates the error category. Your client code should check the status code first, then read the error message for debugging details. Error messages are stable and safe to log but should not be shown to end users.

json

{
  "error": "Invalid API key. Check your key in Dashboard > Settings > API Key."
}

Common HTTP status codes:

Status	Meaning	When it happens
400	Bad Request	Missing or invalid query parameters or request body
401	Unauthorized	Missing or invalid API key in Authorization header
404	Not Found	Snapshot does not exist for the requested path
429	Too Many Requests	Rate limit exceeded — check Retry-After header
500	Internal Server Error	Unexpected server error — retry with exponential backoff

What content types are supported?

Request bodies must be sent as application/json with the appropriate Content-Type header. API metadata responses (job IDs, counts, error messages) are always returned as application/json. Snapshot content is returned as text/html or text/markdown depending on the requested format. The snapshot endpoint wraps the content in a JSON envelope, so the outer response is always JSON regardless of the content format inside.

bash

# POST requests must include Content-Type
curl -X POST \
  -H "Authorization: Bearer ps_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"siteId": "site_abc123", "paths": ["/products/shoes"]}' \
  https://search.perfectline.io/api/v1/snapshot/queue

Next steps

Ready to start using the API? See the GET /v1/snapshot endpoint to fetch your first pre-rendered snapshot, or POST /v1/snapshot/queue to queue pages for rendering.