The Headless Public API, referenced (Pro)

If your frontend is Next.js, Astro, Nuxt, SvelteKit, Gatsby or Faust.js, and WordPress sits behind it as a content backend, the Headless Public API is how that frontend reads RankReady data without authenticating as a user.

It is public, read-only and off by default.

Turning it on

The master toggle is in the RankReady settings once Pro is licensed. Until you enable it, none of the routes below exist. Nothing is exposed by accident.

Endpoints

All routes are under /wp-json/rankready/v1/public/.

• GET /faq/{id} FAQ items for a post.
• GET /summary/{id} the AI summary for a post.
• GET /schema/{id} ready-to-inject JSON-LD.
• GET /post/{id} the combined payload: FAQ, summary and schema in one response.
• GET /post-by-slug/{slug} the same lookup by slug. Accepts a post_type parameter.
• GET /list a paginated index.
• POST /revalidate a cache-invalidation hook for your frontend.

Prefer /post/{id} over three separate calls. One request is one round trip and one cache entry.

Security model

• Published posts of public post types only.
• No secrets, no admin data, no user personal information in any response.
• Pagination is capped at 100 items per page, enforced server-side.
• CORS is restricted to the frontend origins you configure. Leaving the origins list empty means a wildcard, so set it.
• Errors use RFC 7807 Problem Details, served as application/problem+json.

Rate limiting

Requests are limited per real client IP, defaulting to 120 per minute, and the limit is configurable. Authenticated editors and administrators bypass it, so your own testing while logged in does not reflect what an anonymous frontend sees. Test from an incognito window or a server-side fetch.

Since Pro 1.1.0 each request is counted exactly once, including on sites that use Redis or Memcached object caching.

Caching

Responses carry cache headers with a five-minute shared max-age and a one-day stale-while-revalidate window, which suits a CDN in front of WordPress. When you publish a change and need the edge to drop its copy sooner, call POST /revalidate. That route is protected by a shared secret you set, compared using a timing-safe check, and administrators may also call it directly.

Debugging

Responses include X-RR- diagnostic headers, among them a per-request id. Quote that id when reporting a problem with a specific response; it is far more useful than a description of the symptom.