wp_add_post_terms: assign terms to a post
Sets which terms of one taxonomy a post carries.
It replaces by default
The name says "add". The behaviour, unless you pass append: true, is to replace every existing term in that taxonomy.
Calling it with a single tag on a post that has five tags leaves the post with one tag. The other four are gone, and nothing warns you.
This is the single most destructive default in the WordPress tool groups, because the loss is invisible: the write succeeds, the post looks fine, and the missing classification is noticed weeks later when an archive page is short.
Pass append: true whenever you mean to add.
Arguments
| Argument | Required | Meaning |
|---|---|---|
post_id |
Yes | The post to change |
taxonomy |
Yes | Which taxonomy |
terms |
Yes | Term IDs to set |
append |
No | Add to the existing terms instead of replacing |
dry_run |
No | Report without writing |
terms takes term IDs, not names. A term must already exist; create it first with wp_create_term.
Permissions
Allow content writes open, and edit_post on the target post.
Note it is the post capability, not manage_categories. Assigning terms counts as editing the post, so a user who can edit posts but not manage taxonomies can still change a post's categories.
The two safe patterns
To add without losing anything:
Add term 42 to post 412, appending to the existing terms.
To set an exact list, read the current terms first so you know what you are replacing:
Read post 412 and show me its current categories. Then set exactly these: 42 and 57.
Never issue a replacing call without having seen the current state.
The dry run does not show what you would lose
dry_run returns the term IDs it would set. It does not report the terms currently on the post, so it cannot show you what a replacement would remove.
That makes reading the post first the only real safeguard here. The dry run confirms the arguments; it does not confirm the outcome.
One taxonomy at a time
The call affects only the taxonomy you name. Setting categories does not touch tags, and vice versa.
For a post that needs changes in two taxonomies, that means two calls — and two chances to replace something by accident.
Removing all terms
Passing an empty terms array with append false removes every term of that taxonomy from the post. That is a legitimate operation and an easy accident: a client that resolved zero term IDs from a name lookup and called anyway strips the post's classification.
If an assistant reports assigning "no terms", check the post.
What it returns
The resulting term taxonomy IDs, or an error.
Read the post back to see the terms by name:
Apply it, then read post 412 and show me its categories and tags.
In a batch
Retagging many posts is a good MCP job and a bad place to get append wrong — the mistake is repeated across every post.
Pilot on three:
Append term 42 to the first three posts, show me each post's resulting terms, and stop.
Check those three in WordPress before continuing. See Create terms and organize content.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_forbidden |
No edit_post on that post |
| Existing terms disappeared | append was not set |
| All terms disappeared | An empty terms array with append false |
| An error about invalid terms | The IDs do not exist in that taxonomy |
| Nothing changed on the front end | Cache not purged |
Related
wp_create_term— terms must exist firstwp_get_categoriesto find the IDswp_get_post— read before replacing