wp_update_post: update a post
Updates an existing post. The most consequential everyday write in the server, because the target is usually published.
Arguments
| Argument | Required | Meaning |
|---|---|---|
id |
Yes | The post to update |
title |
No | New title |
content |
No | New body |
excerpt |
No | New excerpt |
slug |
No | New slug |
status |
No | New status |
dry_run |
No | Report without writing |
Permissions
Allow content writes open, and edit_post on that specific item — not merely edit_posts. A user who can edit their own posts cannot update someone else's.
Scopes: mcp:read, mcp:write, wp:content:read, wp:content:write.
Only the fields you pass are changed
Fields you omit are left as they are, including the status. Updating a published post without passing status leaves it published.
That makes a targeted edit safe: passing only title changes only the title.
The field to be careful with is content
content replaces the body wholesale. There is no partial update, no merge and no patch.
An assistant asked to "fix the second paragraph" that sends the whole content field has rewritten the entire post, and whatever it did not reproduce faithfully is gone from the live record.
Two defences:
Read first, and bound the instruction.
Read post 412. Change only the opening paragraph. Leave every other paragraph exactly as it is.
Use the dry run. The update dry run returns before and after, which is the cheapest way to see whether "change one paragraph" was understood as you meant it.
Use a dry run and show me the before and after.
Changing the slug changes the URL
slug is not regenerated when the title changes, so a title edit alone does not move the page. Passing slug does, and a changed URL breaks inbound links, bookmarks and search results.
If a slug must change, plan the redirect before the write.
Recovery
Content changes go through the normal WordPress save path, so revisions usually exist for title, content and excerpt. They do not cover terms, meta or the featured image.
Better than relying on revisions: ask for the current values before changing them, so the conversation holds your undo.
Show me the current title and excerpt, then apply the change.
See Recover from a failed write.
What it returns
The updated post in the standard shape, including content.
Read it back independently afterwards. The write response reflects what was saved; an independent read also catches a filter or another plugin altering the value.
Using it well
Read post 412, show me the title, then change only the title to "…" and read it back.
To publish something:
Set post 412 to published.
To unpublish:
Set page 88 to draft.
Both are explicit, which is how status changes should be.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_post_not_found |
Wrong ID, or a non-public post type |
pom_ai_mcp_forbidden |
No edit_post on that item |
| More changed than intended | content was sent wholesale |
| The URL changed | slug was passed |
| The layout broke | Builder content rewritten without reading its structure |
| The site shows the old version | Cache not purged |
Related
wp_get_post— always call this firstwp_update_page- Update a page safely