Request Builder

Request Builder

Use this page as a quickstart recipe for building requests against HeadlessWP Pro.

Quickstart flow

1. Pick your auth mode (cookie session, bearer token, or service account key).
2. Confirm required capabilities at /wp-json/headlesswp/v1/capabilities.
3. Fetch nonce from /wp-json/headlesswp/v1/nonce for cookie-session flows.
4. Call routes under /wp-json/headlesswp/v1/* using JSON payloads.
5. Handle envelopes consistently: success { data, meta }, error { error, meta }.
6. Log correlation IDs for debugging and support.

How to choose auth

Use the auth field in the endpoint registry to decide how to authenticate:

• public: no auth required.
• cookie: requires a WordPress cookie session.
• admin: requires an admin-authenticated context (see the endpoint page).
• machine: requires a machine credential flow (see the endpoint page).

How to handle CSRF

Use the csrf field in the endpoint registry:

• required: include X-WP-Nonce with the request.
• exempt: no nonce header is required.

Fetch a nonce before calling a CSRF-protected cookie route:

curl -i "https://YOUR-WP-SITE.example/wp-json/headlesswp/v1/nonce"

Secure proxy note (this repo)

• The endpoint registry csrf field documents plugin endpoint behavior when calling the WordPress origin directly.
• When calling through this repo's /api/secure/** proxy, nonce requirements are enforced by the proxy endpoint registry requiresProxyNonce rules and each endpoint doc's Proxy nonce required: yes|no line.
• The nonce header name at the proxy boundary is fixed to X-WP-Nonce.

Cookies

Endpoints with auth: cookie require a WordPress cookie session.

const response = await fetch("https://YOUR-WP-SITE.example/wp-json/headlesswp/v1/me", {
  credentials: "include",
});

Capabilities

Use /wp-json/headlesswp/v1/capabilities before calling extension routes and link back to endpoint details for supported parameters and schemas.