How do I read Yoast metadata for a headless WordPress site?

Definition: A headless WordPress site uses WordPress as its content backend with a separate frontend. Yoast's REST API supplies page metadata as prepared HTML or structured JSON for that frontend to render.

Key facts

• As of 17 October 2026, Yoast's REST API documentation maps yoast_head to HTML and yoast_head_json to structured data.
• Yoast's headless support announcement introduces individual metadata keys and values in version 16.7.
• Yoast's endpoint settings guide says the REST API head endpoint is enabled by default.

Which endpoint returns the metadata?

Yoast's REST API documentation gives these request examples:

https://yoast.com/wp-json/wp/v2/posts?slug=wordpress-seo
https://yoast.com/wp-json/yoast/v1/get_head?url=https://yoast.com/wordpress-seo/

The WordPress response includes yoast_head and yoast_head_json when Yoast SEO is active. The URL endpoint returns html, json and status. Their correspondence is:

The URL response's status represents an HTTP status code, typically 200 or 404.

Which format should the frontend use?

Yoast's integration guidance recommends the prepared HTML, which includes metadata tags and schema.org markup for the document's <head>. For custom rendering, the structured object exposes individual values; Yoast recommends comparing the result with its prepared HTML.

A documented schema setting needs particular attention. Yoast's Schema API documentation explains that disabling schema with the wpseo_json_ld_output filter removes schema output from yoast_head, while yoast_head_json retains the schema data. The documentation attributes this difference to separate HTML and JSON code paths: the filter controls the frontend script output, and the raw JSON path bypasses it. A frontend consuming structured metadata therefore needs to account for this difference when implementing schema suppression.

How can a request return fewer fields?

WordPress's global parameters documentation defines _fields, a query parameter that restricts the response properties. Applied to Yoast's documented post request, a metadata-focused request is:

https://yoast.com/wp-json/wp/v2/posts?slug=wordpress-seo&_fields=yoast_head,yoast_head_json

This example combines WordPress's field selection syntax with Yoast's field names. WordPress accepts comma-separated field names and skips unneeded fields while constructing the response. The same documentation explains that reducing the returned properties makes the JSON response smaller. An existing request that selects fields needs to include the required Yoast properties in that selection.

Related terms

• JSON-LD
• Structured data
• How do I set a custom canonical URL in Yoast SEO?
• Why can Yoast's REST API return a missing URL response?

FAQ

Which version provides structured metadata?

Yoast's version 16.7 announcement introduces JSON access with individual keys and values for metadata tags and schema output. It describes this format as support for developers building a separate frontend.

Where can I enable the endpoint?

Yoast's settings instructions place the control under Yoast SEO, Settings, Site features, Technical SEO. Set the REST API endpoint toggle to On and select Save changes.

Can I change metadata through this API?

Yoast's REST API documentation describes the API as read-only. It supports reading metadata; updating it through POST or PUT is unsupported.

Sources

1. Yoast, "Yoast SEO: REST API", undated
2. Yoast, "Yoast SEO 16.7: Extended headless support", 13 July 2021
3. Yoast, "How to disable or enable the REST API endpoint in Yoast SEO", undated
4. Yoast, "Schema - API documentation", undated
5. WordPress, "Global Parameters", updated 14 October 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer