wp-rest-api
wordpress/agent-skills
Build, extend, and debug WordPress REST API endpoints with schema validation, authentication, and custom fields.
What is wp-rest-api?
This skill helps you create and manage WordPress REST API routes, controllers, and custom fields. Use it when registering endpoints, debugging permission/authentication issues, exposing custom post types via REST, or adding computed fields to responses.
- Register custom REST routes and endpoints with proper namespacing and permission callbacks
- Create and extend WP_REST_Controller classes for complex endpoint logic
- Define and validate request arguments using JSON Schema with sanitization
- Add custom fields and meta to REST responses via register_rest_field and register_meta
- Expose custom post types and taxonomies via show_in_rest configuration
- Debug 401/403/404 errors, nonce issues, and permission callback problems
How to install wp-rest-api
npx skills add https://github.com/wordpress/agent-skills --skill wp-rest-api- WordPress 7.0+ (PHP 7.4.0+)
- Filesystem access to plugin/theme/mu-plugin code
- WP-CLI for some workflows (optional but recommended)
- Understanding of WordPress hooks (rest_api_init) and capabilities system
How to use wp-rest-api
- 1.Run project triage to identify the target plugin/theme and existing REST usage
- 2.Choose your approach: expose a CPT/taxonomy via show_in_rest, or register a custom route with register_rest_route
- 3.Define your namespace (e.g., vendor/v1), HTTP methods, and permission_callback
- 4.Create a WP_REST_Controller subclass for non-trivial endpoints or use register_rest_route directly
- 5.Define request argument schema with type, validation, and sanitization callbacks
- 6.Register custom fields via register_rest_field or register_meta with show_in_rest
- 7.Test the endpoint at /wp-json/your-namespace/route and verify OPTIONS returns schema
- 8.Verify authentication/authorization works and permission failures return 401/403 as expected
Use cases
- Building a headless WordPress site with custom API endpoints for a frontend framework
- Adding computed fields (like post reading time or related items) to standard REST responses
- Exposing a custom post type (e.g., testimonials) via REST for mobile app consumption
- Implementing application-password authentication for external client integrations
- Debugging why a custom endpoint returns 403 Forbidden or why fields are missing from responses
- WordPress plugin developers building custom REST endpoints
- Theme developers extending core REST functionality
- Headless WordPress architects designing API contracts
- Full-stack developers integrating WordPress with external applications
wp-rest-api FAQ
show_in_rest exposes an existing post type or taxonomy under wp/v2 with standard CRUD endpoints. register_rest_route creates a custom endpoint with your own logic, namespace, and response shape.
Use application passwords (basic auth) or an auth plugin. For wp-admin/JS, use cookie auth with X-WP-Nonce header (action wp_rest). Always verify capability in permission_callback, not just "logged in" status.
Ensure show_in_rest is true on the meta registration, or use register_rest_field for computed fields. For CPTs, verify custom-fields support is enabled. Check that the field is not filtered out by _fields parameter.
Verify rest_api_init hook is firing, check for route typo, and ensure permalinks are enabled. If permalinks are off, test with ?rest_route=/your-namespace/route. Run /wp-json/ to confirm your namespace appears.
No—do not remove core fields. Instead, add new fields via register_rest_field or register_meta. If you need raw unfiltered content, request ?context=edit (requires auth) to access content.raw.
Full instructions (SKILL.md)
Source of truth, from wordpress/agent-skills.
name: wp-rest-api description: "Use when building, extending, or debugging WordPress REST API endpoints/routes: register_rest_route, WP_REST_Controller/controller classes, schema/argument validation, permission_callback/authentication, response shaping, register_rest_field/register_meta, or exposing CPTs/taxonomies via show_in_rest." compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
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
- Run triage:
node skills/wp-project-triage/scripts/detect_wp_project.mjs
- Search for existing REST usage:
register_rest_routeWP_REST_Controllerrest_api_initshow_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_baseif needed. - Optionally provide
rest_controller_class. - Read
references/custom-content-types.md.
- Use
- Custom endpoints:
- Use
register_rest_route()onrest_api_init. - Prefer a controller class (
WP_REST_Controllersubclass) for anything non-trivial. - Read
references/routes-and-endpoints.mdandreferences/schema.md.
- Use
2) Register routes safely (namespaces, methods, permissions)
- Use a unique namespace
vendor/v1; avoidwp/*unless core. - Always provide
permission_callback(use__return_truefor public endpoints). - Use
WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLEconstants. - Return data via
rest_ensure_response()orWP_REST_Response. - Return errors via
WP_Errorwith an explicitstatus.
Read references/routes-and-endpoints.md.
3) Validate/sanitize request args
- Define
argswithtype,default,required,validate_callback,sanitize_callback. - Prefer JSON Schema validation with
rest_validate_value_from_schemathenrest_sanitize_value_from_schema. - Never read
$_GET/$_POSTdirectly inside endpoints; useWP_REST_Request.
Read references/schema.md.
4) Responses, fields, and links
- Do not remove core fields from default endpoints; add fields instead.
- Use
register_rest_fieldfor computed fields;register_metawithshow_in_restfor meta. - For
object/arraymeta, define schema inshow_in_rest.schema. - If you need unfiltered post content (e.g., ToC plugins injecting HTML), request
?context=editto accesscontent.raw(auth required). Pair with_fields=content.rawto keep responses small. - Add related resource links via
WP_REST_Response::add_link().
Read references/responses-and-fields.md.
5) Authentication and authorization
- For wp-admin/JS: cookie auth +
X-WP-Nonce(actionwp_rest). - For external clients: application passwords (basic auth) or an auth plugin.
- Use capability checks in
permission_callback(authorization), not just “logged in”.
Read references/authentication.md.
6) Client-facing behavior (discovery, pagination, embeds)
- Ensure discovery works (
Linkheader or<link rel="https://api.w.org/">). - Support
_fields,_embed,_method,_envelope, pagination headers. - Remember
per_pageis capped at 100.
Read references/discovery-and-params.md.
Verification
/wp-json/index includes your namespace.OPTIONSon your route returns schema (when provided).- Endpoint returns expected data; permission failures return 401/403 as appropriate.
- CPT/taxonomy routes appear under
wp/v2whenshow_in_restis true. - Run repo lint/tests and any PHP/JS build steps.
Failure modes / debugging
- 404:
rest_api_initnot firing, route typo, or permalinks off (use?rest_route=). - 401/403: missing nonce/auth, or
permission_callbacktoo strict. _doing_it_wrongfor missingpermission_callback: add it (use__return_trueif public).- Invalid params: missing/incorrect
argsschema or validation callbacks. - Fields missing:
show_in_restfalse, meta not registered, or CPT lackscustom-fieldssupport.
Escalation
If version support or behavior is unclear, consult the REST API Handbook and core docs before inventing patterns.
Related skills
More from wordpress/agent-skills and the wider catalog.


