WP REST API

When to use

Use this skill when you need to:

• create or update REST routes/endpoints
• debug 401/403/404 errors or permission/nonce issues
• add custom fields/meta to REST responses
• expose custom post types or taxonomies via REST
• implement schema + argument validation
• adjust response links/embedding/pagination

Inputs required

• Repo root + target plugin/theme/mu-plugin (path to entrypoint).
• Desired namespace + version (e.g. my-plugin/v1) and routes.
• Authentication mode (cookie + nonce vs application passwords vs auth plugin).
• Target WordPress version constraints (if below 7.0, call out).

Procedure

0) Triage and locate REST usage

1. Run triage:
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. Search for existing REST usage:
   • register_rest_route
   • WP_REST_Controller
   • rest_api_init
   • show_in_rest, rest_base, rest_controller_class

If this is a full site repo, pick the specific plugin/theme before changing code.

1) Choose the right approach

• Expose CPT/taxonomy in wp/v2:
  • Use show_in_rest => true + rest_base if needed.
  • Optionally provide rest_controller_class.
  • Read references/custom-content-types.md.
• Custom endpoints:
  • Use register_rest_route() on rest_api_init.
  • Prefer a controller class (WP_REST_Controller subclass) for anything non-trivial.
  • Read references/routes-and-endpoints.md and references/schema.md.

2) Register routes safely (namespaces, methods, permissions)

• Use a unique namespace vendor/v1; avoid wp/* unless core.
• Always provide permission_callback (use __return_true for public endpoints).
• Use WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLE constants.
• Return data via rest_ensure_response() or WP_REST_Response.
• Return errors via WP_Error with an explicit status.

Read references/routes-and-endpoints.md.

3) Validate/sanitize request args