# Prerender Buddy Developer API

The Prerender Buddy Developer API is part of the managed Prerender Buddy platform. It is not an open-source API service.

Use it when you want crawler-readable rendering, diagnostics, cache operations, and integration checks without running the rendering engine yourself.

## Availability

Developer API access is included on Pro, Agency, and custom plans.

Free and Starter plans can use the dashboard and public tools, but hosted Developer API calls are not enabled by default.

## Authentication

Create an API key in the dashboard under API Keys. Store the secret only in server-side configuration, CI secrets, or trusted local developer tools.

Send the key as a bearer token:

```http
Authorization: Bearer pb_live_...
```

The full key is shown only once. Prerender Buddy stores the key hash and prefix, not the raw secret.

## Usage and billing model

Developer API rendering uses the same managed render quota as crawler rendering.

- Fresh renders count against the monthly render quota.
- Cache hits are reported separately.
- Diagnostics that perform a rendered comparison can consume render quota.
- Cache purge, usage, logs, and site listing are rate-limited operations, not render-quota operations.

## Endpoints

### List sites

```http
GET /v1/developer/sites
```

Requires `sites` scope.

Returns the sites available to the API key workspace.

### Usage

```http
GET /v1/developer/usage
```

Requires `usage` scope.

Returns current plan, render quota, requests, cache states, failures, and monthly usage.

### Logs

```http
GET /v1/developer/logs?limit=25
GET /v1/developer/logs?siteId=<site_id>&limit=25
```

Requires `usage` scope.

Returns recent render/API log entries for the workspace.

### Render

```http
POST /v1/developer/render
Content-Type: application/json

{
  "url": "https://example.com/page",
  "includeHtml": true
}
```

Requires `render` scope.

The URL must belong to a site registered in the API key workspace. The response includes status, cache headers, render metadata, and optionally rendered HTML.

### Diagnostics

```http
POST /v1/developer/diagnostics
Content-Type: application/json

{
  "url": "https://example.com/page",
  "mode": "compare"
}
```

Requires `diagnostics` scope.

Modes:

- `compare`: raw HTML versus rendered HTML comparison.
- `signals`: page title, description, canonical, headings, text excerpt, framework/app-shell signals, and metadata gaps.

### Cache purge

```http
POST /v1/developer/cache/purge
Content-Type: application/json

{
  "url": "https://example.com/page"
}
```

Requires `cache` scope.

The URL must belong to a registered site in the API key workspace.

### Verify site integration

```http
POST /v1/developer/sites/:id/verify
Content-Type: application/json

{
  "url": "https://example.com/page"
}
```

Requires `sites` scope.

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

## Errors

Developer API JSON errors use this shape:

```json
{
  "error": {
    "code": "site_not_registered",
    "message": "The URL must belong to a site registered in this API key workspace."
  },
  "requestId": "..."
}
```

Common error codes:

- `missing_api_key`
- `invalid_api_key`
- `developer_api_not_enabled`
- `insufficient_scope`
- `site_not_registered`
- `site_limit_exceeded`
- `quota_exceeded`
- `cache_purge_failed`

## Security boundaries

The Developer API only accepts public HTTP and HTTPS URLs. Private IPs, local hostnames, embedded URL credentials, unsafe redirects, oversized responses, and long-running upstream requests are blocked or bounded.

Internal browser orchestration, provider details, queues, proxy infrastructure, crawler-routing rules, billing internals, and abuse controls are not exposed.

## Related tools

- CLI: `npx @prerenderbuddy/cli`
- MCP: `npx --yes @prerenderbuddy/mcp`
- Managed platform: `https://prerenderbuddy.com`