{"openapi":"3.1.0","info":{"title":"Prerender Buddy Developer API","version":"1.0.0","description":"Managed API for crawler rendering, diagnostics, cache operations, site verification, usage, and logs."},"servers":[{"url":"https://api.prerenderbuddy.com"}],"security":[{"bearerApiKey":[]}],"tags":[{"name":"Workspace"},{"name":"Rendering"},{"name":"Operations"}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"pb_live","description":"Send a server-side API key as `Authorization: Bearer pb_live_...`."}},"schemas":{"ErrorResponse":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"requestId":{"type":"string"}}},"UrlRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","example":"https://example.com/pricing"}}},"RenderRequest":{"allOf":[{"$ref":"#/components/schemas/UrlRequest"},{"type":"object","properties":{"includeHtml":{"type":"boolean","default":true}}}]},"DiagnosticsRequest":{"allOf":[{"$ref":"#/components/schemas/UrlRequest"},{"type":"object","properties":{"mode":{"type":"string","enum":["compare","signals"],"default":"compare"},"excerptChars":{"type":"integer","minimum":200,"maximum":5000}}}]},"Site":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string"},"integrationMode":{"type":"string"},"proxyStatus":{"type":"string"},"cacheTtlMinutes":{"type":"integer"},"withinPlanLimit":{"type":"boolean"},"lastPrerenderAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Plan":{"type":"object","properties":{"name":{"type":"string","enum":["pro","agency","custom"]},"developerApiEnabled":{"type":"boolean"},"siteLimit":{"type":"integer"},"sitesUsed":{"type":"integer"},"renderLimit":{"type":"integer","nullable":true}}},"Usage":{"type":"object","properties":{"plan":{"$ref":"#/components/schemas/Plan"},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"renders":{"type":"integer"},"renderLimit":{"type":"integer","nullable":true},"quotaRemaining":{"type":"integer","nullable":true},"quotaExceeded":{"type":"boolean"},"requests":{"type":"integer"},"cacheHits":{"type":"integer"},"cacheMisses":{"type":"integer"},"staleHits":{"type":"integer"},"quotaExceededEvents":{"type":"integer"},"failures":{"type":"integer"},"averageDurationMs":{"type":"integer"},"requestId":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Plan, scope, or site ownership check failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SiteLimitExceeded":{"description":"The registered site is outside the current plan limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"QuotaExceeded":{"description":"Monthly fresh render quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/developer/sites":{"get":{"tags":["Workspace"],"summary":"List registered sites available to the API key workspace.","description":"Requires the `sites` scope. This operation is read-only.","responses":{"200":{"description":"Site list.","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}},"plan":{"$ref":"#/components/schemas/Plan"},"requestId":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/developer/usage":{"get":{"tags":["Workspace"],"summary":"Get current plan, quota, and Developer API usage.","description":"Requires the `usage` scope. This operation is read-only.","responses":{"200":{"description":"Usage summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/developer/logs":{"get":{"tags":["Workspace"],"summary":"Get recent render/API logs.","description":"Requires the `usage` scope. This operation is read-only.","parameters":[{"name":"siteId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Recent logs."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/developer/sites/{id}/overview":{"get":{"tags":["Workspace"],"summary":"Get a concise setup, monitoring, activity, and AI visibility overview for one site.","description":"Requires the `sites` scope. The site must belong to the API key workspace and remain within its plan limit.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Site overview."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SiteLimitExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/developer/sites/{id}/health":{"get":{"tags":["Workspace"],"summary":"Get bounded website-health, incident, discovery-file, and readiness evidence.","description":"Requires the `health` scope. Full page HTML and unbounded page content are not returned.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Latest health evidence."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SiteLimitExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/developer/sites/{id}/crawler-activity":{"get":{"tags":["Workspace"],"summary":"Get recent real crawler activity grouped by platform and page.","description":"Requires the `activity` scope. Synthetic checks are excluded.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":20}}],"responses":{"200":{"description":"Crawler activity summary."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SiteLimitExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/developer/sites/{id}/visibility":{"get":{"tags":["Workspace"],"summary":"Get AI visibility results by platform, source domain, and tracked competitor.","description":"Requires the `visibility` scope. Returns aggregated evidence without full provider-answer bodies.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":7,"maximum":365,"default":365}}],"responses":{"200":{"description":"AI visibility evidence."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SiteLimitExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/developer/sites/{id}/recommendations":{"get":{"tags":["Workspace"],"summary":"Get evidence-grounded visibility recommendations for the latest completed collection.","description":"Requires the `visibility` scope. Recommendations report evidence limits and do not claim guaranteed outcomes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Visibility diagnosis and recommendations."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SiteLimitExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/developer/sites/{id}/content":{"get":{"tags":["Workspace"],"summary":"List bounded content-calendar and article-draft metadata for one site.","description":"Requires the `content` scope. Draft bodies are not returned.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}],"responses":{"200":{"description":"Content status."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SiteLimitExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/developer/render":{"post":{"tags":["Rendering"],"summary":"Render one registered public URL through the managed Prerender Buddy platform.","description":"Requires the `render` scope. A fresh result consumes the workspace render allowance; cache hits do not.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderRequest"}}}},"responses":{"200":{"description":"Render response with metadata and optional HTML."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SiteLimitExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/developer/diagnostics":{"post":{"tags":["Rendering"],"summary":"Run crawler visibility diagnostics for one registered public URL.","description":"Requires the `diagnostics` scope. A fresh rendered result may consume the workspace render allowance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiagnosticsRequest"}}}},"responses":{"200":{"description":"Diagnostics result."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/developer/cache/purge":{"post":{"tags":["Operations"],"summary":"Purge a cached render for one registered public URL.","description":"Requires the `cache` scope. This is a mutating operation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlRequest"}}}},"responses":{"200":{"description":"Cache purge result."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/developer/sites/{id}/verify":{"post":{"tags":["Operations"],"summary":"Verify whether crawler traffic reaches Prerender Buddy for a registered site.","description":"Requires the `sites` scope and only accepts a URL on the selected registered site.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlRequest"}}}},"responses":{"200":{"description":"Verification result."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}