Wp Rest Api
Add or fix custom WordPress REST routes, auth, and response schema while building a plugin, theme, or headless WordPress product.
Overview
wp-rest-api is an agent skill for the Build phase that implements, extends, and debugs WordPress REST API routes, controllers, schema validation, and authentication.
Install
npx skills add https://github.com/wordpress/agent-skills --skill wp-rest-apiWhat is this skill?
- WordPress 6.9+ workflow with repo triage via detect_wp_project.mjs before edits
- Creates and updates routes with register_rest_route and controller classes
- Debugs 401/403/404, permission_callback, cookie nonce, and application-password auth
- Exposes CPTs/taxonomies via show_in_rest and adds fields with register_rest_field/register_meta
- Implements JSON schema and request argument validation for stable API contracts
- Targets WordPress 6.9+ and PHP 7.2.24+
- Procedure step 0 runs node skills/wp-project-triage/scripts/detect_wp_project.mjs
Adoption & trust: 2.3k installs on skills.sh; 1.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need custom data on the WordPress REST API but hits 401/403/404, weak permissions, or missing schema for your plugin or headless client.
Who is it for?
Indie developers building WordPress plugins, block themes, or headless frontends who own PHP entrypoints and REST contracts.
Skip if: Teams on hosted-only workflows with no repo access, or projects that only need Gutenberg blocks with no custom REST surface.
When should I use this skill?
Building, extending, or debugging WordPress REST API endpoints: register_rest_route, WP_REST_Controller, schema validation, permission_callback, register_rest_field, or CPT/taxonomy show_in_rest.
What do I get? / Deliverables
You get namespaced routes with validated arguments, correct permission_callback behavior, and CPT/meta exposed in REST responses ready for clients or the next integration step.
- Registered REST routes with argument schema and permission callbacks
- Controller classes or callbacks with shaped JSON responses
- CPT/taxonomy and meta fields visible in REST where required
Recommended Skills
Journey fit
REST controllers and route registration are core backend work during implementation, not a separate launch or growth activity. The skill centers on PHP route handlers, WP_REST_Controller patterns, and API-shaped responses rather than frontend UI or DevOps deploy pipelines.
How it compares
Procedural WordPress REST playbook for agents—not a generic OpenAPI generator or a one-shot PHP snippet.
Common Questions / FAQ
Who is wp-rest-api for?
Solo and indie builders maintaining WordPress codebases who register custom REST routes, debug auth, or expose CPTs and meta to apps and agents.
When should I use wp-rest-api?
During Build when adding register_rest_route endpoints, fixing permission/nonce issues, wiring show_in_rest for custom types, or shaping schema and pagination for API consumers.
Is wp-rest-api safe to install?
It guides filesystem edits and shell/Node triage on your repo; review the Security Audits panel on this page and treat REST permission_callback changes as security-sensitive before shipping.
Workflow Chain
Requires first: wp project triage
SKILL.md
READMESKILL.md - Wp Rest Api
# 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 6.9, 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 - Define `args` with `type`, `default`, `required`, `validate_callback`, `sanitize_callback`. - Prefer JSON Schema validation with `rest_validate_value_from_schema` then `rest_sanitize_value_from_schema`. - Never read `$_GET`/`$_POST` directly inside endpoints; use `WP_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_field` for computed fields; `register_meta` with `show_in_rest` for meta. - For `object`/`array` meta, define schema in `show_in_rest.schema`. - If you need unfiltered post content (e.g., ToC plugins injecting HTML), request `?context=edit` to access `content.raw` (auth required). Pair with `_fields=content.raw` to 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` (action `wp_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 (`Link` header or `<link rel="https://api.w.org/">`). - Support `_fields`, `_embed`, `_method`, `_envelope`, pagination headers. - Remember `per_page` is capped at 100. Read `references/discovery-and-params.md`. ## Verification - `/wp-json/` index in