# Prerender Buddy Developer API

Use the managed Developer API to render registered public URLs, diagnose crawler output, manage cached renders, and read scoped workspace evidence.

Base URL: `https://api.prerenderbuddy.com`.

Reference baseline: the [deployed OpenAPI](https://api.prerenderbuddy.com/v1/developer/openapi.json), API version `1.0.0`, inspected September 5, 2026. This reference covers all 13 paths in that contract.

## Access and authentication

Developer API access requires an eligible workspace and a key with the scope required by the operation. The public legacy catalog includes Developer API access on Pro, Agency and custom plans. For accounts on another catalog, check the effective Developer API entitlement in the account; a shared plan name alone does not establish access.

Create a scoped Developer API key in the account's API key area. Store it in a server-side secret or trusted local environment and send:

```http
Authorization: Bearer <your-scoped-api-key>
```

Do not put the key in browser JavaScript, public repositories, screenshots, or shared logs. Use only the scopes your integration needs. Follow the site's authenticated setup instructions for rendering/setup credentials; do not assume a setup credential is interchangeable with a scoped Developer API key.

The examples use `PRERENDER_BUDDY_API_KEY` as a local variable containing your key, and `PB_SITE_ID` for an actual UUID returned by the sites endpoint. These are example client variables, not additional API fields. Example URLs are illustrative: replace them with public URLs on a site registered to your workspace.

## Workspace and URL boundaries

Site data belongs to the API key's workspace. Use returned registered-site IDs; an ID from another account does not grant access. Site access also depends on effective plan limits. The contract documents `402` for a site outside the plan limit on the six site-read endpoints and the render endpoint.

Rendering and URL operations accept registered public HTTP/HTTPS URLs. Private IPs, local hostnames and unsafe redirects are blocked or bounded by the managed service. The verification URL must belong to the selected registered site. Keep site-specific integration snippets and exact setup/verification values in the authenticated setup context.

## Endpoint and scope index

| Endpoint | Required scope | Purpose |
| --- | --- | --- |
| `GET /v1/developer/sites` | `sites` | List registered sites available to the API key workspace. |
| `GET /v1/developer/usage` | `usage` | Get current plan, quota, and Developer API usage. |
| `GET /v1/developer/logs` | `usage` | Get recent render/API logs. |
| `GET /v1/developer/sites/{id}/overview` | `sites` | Get a concise setup, monitoring, activity, and AI visibility overview for one site. |
| `GET /v1/developer/sites/{id}/health` | `health` | Get bounded website-health, incident, discovery-file, and readiness evidence. |
| `GET /v1/developer/sites/{id}/crawler-activity` | `activity` | Get recent real crawler activity grouped by platform and page. |
| `GET /v1/developer/sites/{id}/visibility` | `visibility` | Get AI visibility results by platform, source domain, and tracked competitor. |
| `GET /v1/developer/sites/{id}/recommendations` | `visibility` | Get evidence-grounded visibility recommendations for the latest completed collection. |
| `GET /v1/developer/sites/{id}/content` | `content` | List bounded content-calendar and article-draft metadata for one site. |
| `POST /v1/developer/render` | `render` | Render one registered public URL through the managed Prerender Buddy platform. |
| `POST /v1/developer/diagnostics` | `diagnostics` | Run crawler visibility diagnostics for one registered public URL. |
| `POST /v1/developer/cache/purge` | `cache` | Purge a cached render for one registered public URL. |
| `POST /v1/developer/sites/{id}/verify` | `sites` | Verify whether crawler traffic reaches Prerender Buddy for a registered site. |

## Request fields

JSON requests use `Content-Type: application/json`.

| Body | Field | Requirement and meaning |
| --- | --- | --- |
| `UrlRequest` | `url` | Required URI string; use a registered public URL. |
| `RenderRequest` | `url` | Required; same URL boundary. |
| `RenderRequest` | `includeHtml` | Optional boolean; defaults to `true`. |
| `DiagnosticsRequest` | `url` | Required; same URL boundary. |
| `DiagnosticsRequest` | `mode` | Optional `compare` or `signals`; defaults to `compare`. |
| `DiagnosticsRequest` | `excerptChars` | Optional integer from 200 to 5,000; no default specified in this contract. |

## Start with a workspace read

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $PRERENDER_BUDDY_API_KEY" \
  https://api.prerenderbuddy.com/v1/developer/sites
```

The documented JSON response contains `sites`, `plan` and `requestId`. Site fields include `id`, `name`, `domain`, `status`, `integrationMode`, `proxyStatus`, `cacheTtlMinutes`, `withinPlanLimit`, `lastPrerenderAt`, `createdAt` and `updatedAt`. The schema does not mark these site properties as required; clients should handle absent values. `lastPrerenderAt` may be null.

Minimal illustrative response using fields defined by the schema; this is not a captured customer response:

```json
{
  "sites": [],
  "requestId": "illustrative-request-id"
}
```

This partial example omits plan and site details. Use the account's actual returned entitlement values. A nullable `renderLimit` is not, by itself, a documented promise of unlimited service.

## Read saved evidence for a site

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $PRERENDER_BUDDY_API_KEY" \
  "https://api.prerenderbuddy.com/v1/developer/sites/$PB_SITE_ID/overview"

curl --fail-with-body \
  -H "Authorization: Bearer $PRERENDER_BUDDY_API_KEY" \
  "https://api.prerenderbuddy.com/v1/developer/sites/$PB_SITE_ID/crawler-activity?days=30&limit=20"

curl --fail-with-body \
  -H "Authorization: Bearer $PRERENDER_BUDDY_API_KEY" \
  "https://api.prerenderbuddy.com/v1/developer/sites/$PB_SITE_ID/visibility?days=30"
```

These reads expose bounded evidence, not an instruction to run a new scan or collection. The health response excludes full page HTML and unbounded page content; visibility excludes full provider-answer bodies; content returns calendar/draft metadata without article bodies. Crawler activity excludes synthetic checks.

Use the recorded scope, dates and evidence status when interpreting data. Unavailable or incomplete evidence must not be converted into a zero score or a claim that the brand is absent. Crawler request activity does not establish indexing or a citation. A source returned during a provider run is not necessarily an explicit citation in its answer.

The current OpenAPI describes the purpose of these six responses without defining their JSON properties. Consult the verified response schema before binding client logic to fields.

## Render a registered public URL

This operation may consume fresh-render allowance.

```bash
curl --fail-with-body \
  -X POST https://api.prerenderbuddy.com/v1/developer/render \
  -H "Authorization: Bearer $PRERENDER_BUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com/pricing","includeHtml":true}'
```

The contract describes a response containing metadata and optional HTML. `includeHtml: false` requests omission of HTML; it does not mean no rendering work occurs. The contract does not define the complete response properties.

## Diagnose a registered public URL

```bash
curl --fail-with-body \
  -X POST https://api.prerenderbuddy.com/v1/developer/diagnostics \
  -H "Authorization: Bearer $PRERENDER_BUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com/pricing","mode":"compare","excerptChars":1000}'
```

Use `compare` for raw-versus-rendered diagnostics or `signals` for page-signal extraction. A fresh rendered result may consume allowance. This managed diagnostic operation differs from the local public HTTP diagnostics exposed by the CLI/MCP package.

## Cache and usage

Fresh managed API renders draw on the workspace render allowance. Cache hits do not consume fresh-render allowance. Ordinary visitor traffic must not be counted as fresh rendering merely because it passes through an integration.

`GET /v1/developer/usage` reports the contract's plan, period, renders, renderLimit, quotaRemaining, quotaExceeded, requests, cacheHits, cacheMisses, staleHits, quotaExceededEvents, failures, averageDurationMs and requestId fields. Nullable limits and missing fields need deliberate handling. Use the response period rather than assuming a calendar-month boundary.

Illustrative partial usage response, showing only schema-defined fields:

```json
{
  "renders": 12,
  "cacheHits": 28,
  "cacheMisses": 12,
  "staleHits": 0,
  "quotaExceeded": false,
  "requestId": "illustrative-usage-request"
}
```

The values demonstrate types only; they are not measured performance or billing evidence.

To invalidate one cached registered URL, use `POST /v1/developer/cache/purge` with `UrlRequest`. This changes cache state. Purging and obtaining a new rendered result are separate operations; the contract does not promise an immediate background refresh or prescribe stale-serving behavior.

Use `GET /v1/developer/logs` for recent render/API activity. Its `limit` defaults to 25 and supports 1–100; `siteId` optionally selects a site. The contract does not specify a pagination cursor.

## Verification

`POST /v1/developer/sites/{id}/verify` accepts `UrlRequest`, requires the `sites` scope, and checks crawler routing for the selected registered site. Obtain the correct site and verification URL from the authenticated setup context. Verification of routing is not proof of indexing, rankings, citations or recommendations.

## Errors

The documented error envelope has this shape. Angle-bracket values below are explanatory placeholders, not literal error codes:

```json
{
  "error": {
    "code": "<machine-readable-code>",
    "message": "<explanation>",
    "details": {}
  },
  "requestId": "<request-id>"
}
```

`error` and `requestId` are required; `code` and `message` are required within `error`; `details` is optional.

| HTTP status | Meaning in this contract | Next action |
| --- | --- | --- |
| `401` | Missing or invalid key | Check the server-side key and authorization header. |
| `402` | Registered site outside plan limit, on endpoints that document it | Check account/site allowance; do not treat it as a missing site. |
| `403` | Plan, scope or ownership check failed | Inspect the error and verify the workspace entitlement, required scope and site ownership. |
| `404` | Requested resource not found, where documented | Check the registered-site ID and requested route. |
| `429` | Fresh-render quota exceeded on render/diagnostics | Inspect current usage; repeated immediate retries do not restore allowance. |

The endpoint sections below show exactly which statuses the OpenAPI lists for each operation. They are not a claim that networks, gateways or other runtime failures can never produce additional statuses. Log request IDs and sanitized error details without logging secrets or sensitive page content.

## Per-endpoint contract details

### GET /v1/developer/sites

List registered sites available to the API key workspace.

Requires the `sites` scope. This operation is read-only.

Documented response statuses: `200`, `401`, `403`.

### GET /v1/developer/usage

Get current plan, quota, and Developer API usage.

Requires the `usage` scope. This operation is read-only.

Documented response statuses: `200`, `401`, `403`.

### GET /v1/developer/logs

Get recent render/API logs.

Requires the `usage` scope. This operation is read-only.

| Parameter | Location | Type | Allowed values / default |
| --- | --- | --- | --- |
| `siteId` | query | string | uuid |
| `limit` | query | integer | 1–100; default 25 |

Documented response statuses: `200`, `401`, `403`.

### GET /v1/developer/sites/{id}/overview

Get a concise setup, monitoring, activity, and AI visibility overview for one site.

Requires the `sites` scope. The site must belong to the API key workspace and remain within its plan limit.

| Parameter | Location | Type | Allowed values / default |
| --- | --- | --- | --- |
| `id` | path | string | required; uuid |

Documented response statuses: `200`, `401`, `402`, `403`, `404`.

### GET /v1/developer/sites/{id}/health

Get bounded website-health, incident, discovery-file, and readiness evidence.

Requires the `health` scope. Full page HTML and unbounded page content are not returned.

| Parameter | Location | Type | Allowed values / default |
| --- | --- | --- | --- |
| `id` | path | string | required; uuid |

Documented response statuses: `200`, `401`, `402`, `403`, `404`.

### GET /v1/developer/sites/{id}/crawler-activity

Get recent real crawler activity grouped by platform and page.

Requires the `activity` scope. Synthetic checks are excluded.

| Parameter | Location | Type | Allowed values / default |
| --- | --- | --- | --- |
| `id` | path | string | required; uuid |
| `days` | query | integer | 1–365; default 30 |
| `limit` | query | integer | 1–25; default 20 |

Documented response statuses: `200`, `401`, `402`, `403`, `404`.

### GET /v1/developer/sites/{id}/visibility

Get AI visibility results by platform, source domain, and tracked competitor.

Requires the `visibility` scope. Returns aggregated evidence without full provider-answer bodies.

| Parameter | Location | Type | Allowed values / default |
| --- | --- | --- | --- |
| `id` | path | string | required; uuid |
| `days` | query | integer | 7–365; default 365 |

Documented response statuses: `200`, `401`, `402`, `403`, `404`.

### GET /v1/developer/sites/{id}/recommendations

Get evidence-grounded visibility recommendations for the latest completed collection.

Requires the `visibility` scope. Recommendations report evidence limits and do not claim guaranteed outcomes.

| Parameter | Location | Type | Allowed values / default |
| --- | --- | --- | --- |
| `id` | path | string | required; uuid |

Documented response statuses: `200`, `401`, `402`, `403`, `404`.

### GET /v1/developer/sites/{id}/content

List bounded content-calendar and article-draft metadata for one site.

Requires the `content` scope. Draft bodies are not returned.

| Parameter | Location | Type | Allowed values / default |
| --- | --- | --- | --- |
| `id` | path | string | required; uuid |
| `limit` | query | integer | 1–50; default 25 |

Documented response statuses: `200`, `401`, `402`, `403`, `404`.

### POST /v1/developer/render

Render one registered public URL through the managed Prerender Buddy platform.

Requires the `render` scope. A fresh result consumes the workspace render allowance; cache hits do not.

Documented response statuses: `200`, `401`, `402`, `403`, `429`.

Request body: `RenderRequest`; see Request fields above.

### POST /v1/developer/diagnostics

Run crawler visibility diagnostics for one registered public URL.

Requires the `diagnostics` scope. A fresh rendered result may consume the workspace render allowance.

Documented response statuses: `200`, `401`, `403`, `429`.

Request body: `DiagnosticsRequest`; see Request fields above.

### POST /v1/developer/cache/purge

Purge a cached render for one registered public URL.

Requires the `cache` scope. This is a mutating operation.

Documented response statuses: `200`, `401`, `403`.

Request body: `UrlRequest`; see Request fields above.

### POST /v1/developer/sites/{id}/verify

Verify whether crawler traffic reaches Prerender Buddy for a registered site.

Requires the `sites` scope and only accepts a URL on the selected registered site.

| Parameter | Location | Type | Allowed values / default |
| --- | --- | --- | --- |
| `id` | path | string | required; uuid |

Documented response statuses: `200`, `401`, `403`, `404`.

Request body: `UrlRequest`; see Request fields above.

## Related references

- [Human-readable Developer API overview](https://prerenderbuddy.com/developer-api)
- [Live OpenAPI contract](https://api.prerenderbuddy.com/v1/developer/openapi.json)
- [Developer tools](https://prerenderbuddy.com/developer-tools)
- [Self-hosting overview](https://prerenderbuddy.com/self-hosting)