WordPress Content REST API

intent

use this skill to safely read, create, update, and delete wordpress content (posts, pages, media, categories, tags) via the wordpress rest api. apply it when you need to manage content programmatically without touching server admin, plugins, themes, or cli commands. the skill enforces a dry-run-first pattern, draft-by-default writing, and explicit approval gates before publishing or bulk changes on live sites.

inputs

wordpress instance details:

• base url (e.g., https://example.com or https://staging.example.com)
• environment flag (production or staging) to guard destructive operations
• api version (default: wp/v2, which is stable and widely supported)

authentication:

• auth type: either application password or bearer token (see references/auth.md)
  • application password: username + password, base64-encoded in Authorization: Basic header
  • bearer token: jwt or oauth token in Authorization: Bearer header
• store credentials in env vars: WP_AUTH_USER, WP_AUTH_PASS, WP_AUTH_TOKEN (never hardcode)
• credentials must have rest api permission for the target routes

external connections:

• wordpress rest api endpoint at {base_url}/wp-json/wp/v2/...
• network access to the wordpress site (firewall, proxy, vpn if required)

context from earlier steps:

• current post/page/media id (if updating existing content)
• taxonomy ids (category, tag) that already exist on the site
• media attachment ids (if embedding media in posts)
• author id (if assigning to a user other than the api user)

optional filters and search:

• search term (for full-text post search)
• pagination params (per_page, page, offset)
• status filter (draft, publish, pending, scheduled)
• author filter (user id)
• category/tag ids (to filter by taxonomy)

procedure

1. validate auth and connectivity

   • input: base url, auth credentials (user/pass or bearer token), environment flag
   • call GET {base_url}/wp-json/wp/v2/posts?per_page=1 with auth header
   • output: http 200 and valid json response, or error log if auth fails, network unreachable, or base url is wrong
   • if auth fails, stop and request valid credentials
   • if base url is staging but operation is marked production, stop and ask for confirmation

2. discover target content

   • input: search term (optional), status filter (optional), per_page (default 10), page (default 1)
   • call GET {base_url}/wp-json/wp/v2/posts?search={term}&status={status}&per_page={per_page}&page={page} (or equivalent for pages/media)
   • output: list of objects with id, title, content, status, date, author, featured_media, categories, tags
   • parse response headers for total count (X-WP-Total header)
   • if result set is empty, return empty list and note that no matching content was found
   • if pagination limit is hit (typically 100 posts per page), recommend narrowing search or looping with page param

3. fetch current object for update or read

   • input: content id, content type (post/page/media)
   • call GET {base_url}/wp-json/wp/v2/{type}/{id}?_fields=id,title,content,excerpt,status,author,featured_media,categories,tags,date,modified,meta
   • output: full object json with all writable and readable fields
   • if 404, content does not exist; stop and report
   • if 403, insufficient permission to read; stop and request elevated credentials

4. validate dependent ids (dry-run phase)

   • input: payload to create/update (contains author_id, featured_media_id, category_ids, tag_ids)
   • for each referenced id: call GET {base_url}/wp-json/wp/v2/{resource_type}/{id} (author via /users/{id}, category via /categories/{id}, tag via /tags/{id}, media via /media/{id})
   • output: validation report listing which ids exist and which do not
   • if any id does not exist, halt and list missing ids
   • if featured_media or category/tag ids are invalid, do not proceed to write step

5. prepare and preview payload (dry-run phase)

   • input: requested changes (title, content, status, author, featured_media, categories, tags, meta)
   • construct json payload with only the fields being changed (do not include unchanged fields)
   • verify status is draft unless explicitly instructed to publish
   • verify payload is valid json and does not contain html/script injection in title/content (basic sanitization: check for <script> tags, report if found)
   • output: json payload ready to send, printed for human review
   • if any field is missing or malformed, report and request correction

6. execute write (create or update)

   • input: validated payload from step 5, content id (if updating), content type
   • if creating new content: call POST {base_url}/wp-json/wp/v2/{type} with payload
   • if updating existing content: call PUT {base_url}/wp-json/wp/v2/{type}/{id} or PATCH {base_url}/wp-json/wp/v2/{type}/{id} with payload
   • output: response object with id, status, date, modified, link
   • if response is 201 (created) or 200 (updated), proceed to step 7
   • if response is 400, return error message and request corrected payload
   • if response is 403, stop and report insufficient permission
   • if response is 429, apply exponential backoff (wait 2s, retry; if fails again, wait 4s and retry once more; then fail)
   • if response is 500+, log error and retry up to 2 times with 3s delay between retries
   • if network timeout (no response after 30s), log and retry once; if timeout persists, fail

7. re-read and compare (verification)

   • input: id returned from step 6
   • call GET {base_url}/wp-json/wp/v2/{type}/{id}?_fields=id,title,content,status,author,featured_media,categories,tags,modified
   • output: object json confirming all requested fields match payload
   • compare each field in response against the payload sent in step 6
   • if status is draft and was requested to be draft, mark as success
   • if any field does not match, log the discrepancy and mark operation as partial failure (note next action: manual review or retry)
   • if featured_media or taxonomies do not reflect the payload, retry step 6 once, then report

8. publish only on explicit instruction

   • input: boolean flag approve_publish (defaults to false), content id
   • if approve_publish is false, stop here and report that content is in draft and waiting for approval
   • if approve_publish is true and environment is production, call PATCH {base_url}/wp-json/wp/v2/{type}/{id} with payload {"status":"publish"}
   • output: response with status field set to publish
   • if 200, re-read object to confirm publish date is set
   • if environment is staging, skip this step (do not auto-publish to staging)
   • if any error, report and do not mark content as published

9. handle errors and retries

   • input: http error code, error message from api
   • if 400 (bad request): parse error response, identify the invalid field, report to user with suggestion to correct and retry step 6
   • if 401 (unauthorized): auth token has expired or is invalid, request fresh credentials and retry
   • if 403 (forbidden): api user lacks permission for this operation, request elevated credentials or different user
   • if 404: content or referenced id does not exist, report and do not retry
   • if 429 (rate limit): wait 2s, then 4s, then fail; advise user to wait before retrying
   • if 500+ (server error): wait 3s and retry up to 2 times, then fail and report as transient issue
   • if network error (timeout, connection refused): wait 3s, retry once, then fail and report

decision points

• if base url is staging and operation is marked destructive (bulk delete, publish), stop and ask for explicit environment override. else proceed normally.

• if auth type is application password, use http basic auth (base64-encoded user:pass in Authorization header). else if auth type is bearer token, use Bearer header with token value.

• if search or filter returns zero results, return empty list and stop. else proceed to discover content.

• if any referenced id (author, media, category, tag) does not exist, halt and report missing ids. else proceed to write.

• if status is not explicitly set in the payload, default to draft. else respect the requested status.

• if approve_publish is true and environment is production, attempt to publish. else if approve_publish is false or environment is staging, leave content in draft status.

• if http response is 429 (rate limit), apply exponential backoff (2s, then 4s), retry twice, then fail. else if response is 5xx (server error), wait 3s and retry up to 2 times, then fail.

• if http response is 401 (unauthorized), request fresh auth credentials. else if response is 403 (forbidden), request elevated credentials or different api user.

• if network timeout occurs after 30s, log and retry once; if timeout persists, fail. else proceed normally.

• if re-read in step 7 reveals mismatched fields, retry write once, then report partial failure. else mark operation as complete.

output contract

success response format (json):

{
  "id": 123,
  "title": "post title",
  "content": "post body html",
  "status": "draft",
  "author": 1,
  "featured_media": 456,
  "categories": [10, 11],
  "tags": [20, 21],
  "date": "2024-01-15T10:30:00",
  "modified": "2024-01-15T11:45:00",
  "link": "https://example.com/2024/01/15/post-title/",
  "_fields": ["id", "title", "content", "status", "author", "featured_media", "categories", "tags", "date", "modified", "link"]
}

file location: none (all operations are api calls; responses are json in memory or logged to stdout)

changelog entry (for content updates):

• record id, old status, new status, changed fields, timestamp, api user
• example: post 123 updated: title changed from 'old' to 'new', status remains draft, modified 2024-01-15T11:45:00

error response format:

{
  "code": "rest_invalid_param",
  "message": "Invalid parameter(s): <field_name>",
  "data": {
    "status": 400,
    "params": { "field_name": "error detail" }
  }
}

partial failure log:

• include step at which failure occurred (e.g., "step 6: write failed; step 7: re-read confirmed mismatch in featured_media")
• list fields that did not match
• include next action (e.g., "retry write", "manual review", "check media id validity")

outcome signal

the skill has worked when:

• http response status is 200 (update) or 201 (create) after step 6
• re-read in step 7 confirms all requested fields match the payload sent
• final status matches explicit instruction (draft unless approve_publish is true)
• no errors or only documented partial failures with clear next actions
• if publishing, the response includes a publish_date field and status: publish

user-facing confirmation:

• "draft created: post 123, title 'example', ready for review"
• "post 123 updated: status remains draft, 2 fields changed, re-read confirmed"
• "post 123 published: now live at https://example.com/2024/01/15/example/"
• "operation failed: step 6 write returned 400, field 'categories' contains invalid id 999; retry with valid category ids"

logging:

• log all api calls (method, url, status code, response time) for audit
• log auth failures and rate-limit hits with timestamp
• log partial failures with step number and mismatch details
• do not log auth credentials or bearer tokens in plain text