Rank Math is automatable in three layers through the WordPress REST API: per-post SEO fields (title, description, canonical URL, schema type) stored as
rank_math_*post meta, read-back verification through Rank Math’s owngetHeadendpoint, and the account-level role that decides what any of this can touch. What is not automatable at all is the settings layer – sitemap configuration, global title templates, redirections, the 404 monitor – all of it lives in wp-admin, with no REST route Rank Math documents for changing it. We drive this site’s Rank Math setup through the first two layers every day, and we have hit real production failures doing it: an entity-encoding mismatch in read-verify checks, a WAF that blocks an unbranded HTTP client, and a sitemap cache that has frozen mid-publish more than once.
We publish through this exact setup – the pipeline that wrote this article authenticates to WordPress the same way described below, and the failures further down are our own, pulled from our operating log, not hypothetical.
Registering rank_math_* meta for REST (the bridge-plugin pattern)
Rank Math stores everything it manages per post – title, description, focus keyword, canonical URL – as ordinary WordPress post meta, under keys like rank_math_title, rank_math_description, and rank_math_focus_keyword. That part is well documented. What is not is that Rank Math has no REST API of its own for writing to those fields. Its own support team states this plainly: they do not have a REST API to change the meta programmatically, and point developers instead at WordPress core’s own update_post_meta() function. One support thread references a write endpoint by name, but a separate, more direct ticket from the same team contradicts it – so we are not repeating the unconfirmed one.
The practical path is a bridge: register each rank_math_* key yourself with WordPress core’s register_post_meta(), setting show_in_rest => true per key. Once registered, those fields appear on the standard meta object of /wp/v2/posts, readable and writable through the same authenticated request that creates or updates the post itself – no separate call, no separate plugin API. This is the pattern we run in production: our create-post payload sets rank_math_title, rank_math_description, rank_math_focus_keyword, and rank_math_canonical_url directly inside meta on a single POST /wp/v2/posts call.
The trap sits one step earlier. If a given rank_math_* key was never registered with show_in_rest, WordPress does not reject the request or warn you. It silently drops the field. The API call still returns a clean success – the post gets created, the response comes back 200 or 201 – and the SEO fields are simply blank in wp-admin. Rank Math’s own support queue describes this exact failure: a post created successfully via REST, fields empty, no error to explain why. The only way to catch it is to read the field back after writing and check it landed, which is the next problem.
Read-verify loops with getHead – and the entity-encoding trap
Rank Math does ship one official REST endpoint, and it is read-only: getHead, under its Headless CMS Support module, at /wp-json/rankmath/v1/getHead?url=<full-url>. It takes a complete URL, not a slug, and returns the entire rendered <head> block Rank Math would output on that page – title tag, meta description, canonical, Open Graph, and the JSON-LD schema, all in one response. There is no per-field version; you get the whole block and parse out what you need.
That makes getHead useful for a verification step after publish: fetch it, confirm the title and description actually rendered, confirm the canonical points where you expect. We ran this check while writing this article, and it surfaced a mismatch that has nothing to do with Rank Math and everything to do with how WordPress renders text. We compared a live post’s title through the authenticated, editor-context field (title.raw) against the same title through the public field (title.rendered). The raw field gave a plain straight apostrophe; the rendered field gave the same word with an HTML entity in its place – WordPress’s typography pass runs on .rendered but not .raw. A read-verify loop doing simple string comparison will flag a false mismatch on any title with an apostrophe, quotation mark, or dash. The fix: decode entities before comparing, or compare against .raw – but until you hit it once, the false alarm looks exactly like real drift.
What broke for us in production
Three failures, all logged as they happened, not reconstructed afterward.
Sitemap cache freeze. Rank Math’s XML sitemap is cached, and on this site that cache has frozen outright – its lastmod timestamp stops advancing, and posts published after the freeze point are missing from the sitemap entirely, not just showing a stale date. This has recurred five separate times on this property, each time re-freezing at the timestamp of the most recent publish. We do not currently run a daily check on sitemap membership, so a freeze can sit undetected for days before a routine audit catches it.
WAF blocks on the client, not the request. The account and the request can both be correct and still get blocked – our WordPress client using Python’s plain urllib with no custom User-Agent header intermittently drew an HTTP 403 from this site’s WAF, a Cloudflare-side block. Sending a browser-style User-Agent, or switching to a tool like curl that sets one by default, cleared it. The block was intermittent, which made it look like a flaky network issue the first time, not a client-identity problem.
Role scoping, enforced at the API. The account our agent authenticates as can create, edit, and publish posts and set page-level SEO meta. It cannot purge the sitemap cache, because that needs the manage_options capability, deliberately withheld. Every attempt returns HTTP 403 rest_forbidden – not a partial success. We cover this role-inheritance limit in our application-passwords setup guide – the password inherits whatever the account can do, so the account, not the password, is the real control.
When to stop automating and open wp-admin
Everything covered so far – title, description, canonical, focus keyword, schema type – is per-post meta, which is what register_post_meta and getHead can reach. Rank Math’s site-wide settings are a different layer: general settings, sitemap configuration, global title and meta templates, schema defaults, the redirections list, the 404 monitor. None of it showed up as a REST route in anything Rank Math documents, and every support answer we reviewed pointed back to wp-admin, not an API call. That tracks with how WordPress core works generally – the REST API does not expose arbitrary plugin options tables by default, so a plugin has to deliberately build and document a settings-level route, and Rank Math has not done that for this layer.
In practice, that is where we draw the line. We automate what happens on a per-post basis every time we publish – the repeatable, checkable part. We do not script sitewide settings changes, because there is no supported surface for it and no way to verify the change landed the way getHead lets us verify a post’s meta. When a change belongs at that level, someone opens wp-admin. This maps to the access tiers in our notes on AI SEO agent permissions: the further a change reaches from a single post toward site-wide configuration, the more it belongs to a human in the dashboard, not an agent making REST calls.
None of this replaces the plugin-level checks we already run for on-page SEO across the rest of this site – the same plugin-can’t-do-everything gaps apply here, and the agent architecture underneath this pipeline is the same one behind how our Claude-based agent runs this site. Rank Math automation is one piece of that loop, not a separate system.
Frequently asked questions
Can you update Rank Math’s SEO fields through its own REST API?
Not through a dedicated Rank Math write endpoint – their own support team says they don’t have one, and points to WordPress core’s update_post_meta() instead. In practice, that means registering each rank_math_* key with register_post_meta() and show_in_rest => true, so the fields become writable through the standard /wp/v2/posts meta object.
What happens if a rank_math_* field isn’t registered for REST?
The request does not fail. WordPress silently drops the field, the post still saves, and the Rank Math value is simply left blank – a pattern confirmed independently in Rank Math’s own support queue. The only reliable way to catch it is to read the field back after writing and confirm it landed.
What is the getHead endpoint, and what does it return?
getHead is Rank Math’s official read-only REST endpoint for headless setups, at /wp-json/rankmath/v1/getHead?url=<full-url>. It requires a complete URL rather than a slug and returns the entire rendered head block for that page – title, meta description, canonical, Open Graph tags, and JSON-LD schema together, with no per-field retrieval option.
Can Rank Math’s site-wide settings be automated through the REST API?
Not that Rank Math documents. Site-wide settings – sitemap configuration, global title templates, schema defaults, redirections, the 404 monitor – live in the wp-admin dashboard. Every automation mechanism Rank Math describes (registered post meta, update_post_meta, getHead) is scoped to individual posts, not sitewide configuration.
Leave a Reply