rank-math/update-primary-term sets or clears the Rank Math primary term for a post and taxonomy. Pass a term ID of 0 to clear it.
A term the post is not assigned to is refused rather than written.
At a glance
| Ability | rank-math/update-primary-term |
| Toolset | Rank Math — toolset/rank-math |
| Group | Rank Math › Content SEO |
| Requires | Rank Math SEO, active on the site |
| Capability | manage_options |
| Safety | Writes data |
| Repeatable | Idempotent — running it twice leaves the same result |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
The refusal is the feature
Rank Math accepts any term ID as a primary term and validates nothing. If the post does not have that term, Rank Math ignores the setting at render time and falls back to its default — so the write succeeds, the admin shows the new primary term, and the breadcrumb and permalink do not change.
That is a write that appears to have worked and did not, which is the failure this suite refuses to pass along. The term is checked against the post’s assignments first.
Clearing is a real operation, not just an absence. With no primary term, Rank Math picks by its own ordering — usually the lowest term ID — which is deterministic but arbitrary.
On a site using %category% permalinks, changing the primary term changes the URL of the post. That is a redirect-worthy event, and rank-math/create-redirection is next door.
Idempotent.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
post_id | integer | Yes | The post ID. |
taxonomy | string | Yes | The taxonomy. |
term_id | integer | Yes | The term to make primary, or 0 to clear it. |
What comes back
| Name | Type | What it is |
|---|---|---|
primary_term | object | The primary term after the write. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Make “Guides” the primary category for post 412.
It resolves to one call:
{
"ability": "rank-math/update-primary-term",
"parameters": {
"post_id": 412,
"taxonomy": "category",
"term_id": 87
}
}Worth knowing
- An unassigned term is refused, not silently ignored.
term_id: 0clears it and hands the choice back to Rank Math’s default ordering.- On
%category%permalink sites this changes the post’s URL. Redirect the old one. - Idempotent.
Related abilities
- Get Rank Math Primary Term — read the valid options first
- Create Rank Math Redirection — if the URL changed
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category