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_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 includes your namespace.
OPTIONS on your route returns schema (when provided).
- Endpoint returns expected data; permission failures return 401/403 as appropriate.
- CPT/taxonomy routes appear under
wp/v2 when show_in_rest is true.
- Run repo lint/tests and any PHP/JS build steps.
Failure modes / debugging
- 404:
rest_api_init not firing, route typo, or permalinks off (use ?rest_route=).
- 401/403: missing nonce/auth, or
permission_callback too strict.
_doing_it_wrong for missing permission_callback: add it (use __return_true if public).
- Invalid params: missing/incorrect
args schema or validation callbacks.
- Fields missing:
show_in_rest false, meta not registered, or CPT lacks custom-fields support.
Escalation
If version support or behavior is unclear, consult the REST API Handbook and core docs before inventing patterns.
1---
2name: wp-rest-api
3description: "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."
4compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
5metadata:
6 source: https://skillmd.com/skills/wordpress/wp-rest-api
7---
8
9# WP REST API
10
11## When to use
12
13Use this skill when you need to:
14
15- create or update REST routes/endpoints
16- debug 401/403/404 errors or permission/nonce issues
17- add custom fields/meta to REST responses
18- expose custom post types or taxonomies via REST
19- implement schema + argument validation
20- adjust response links/embedding/pagination
21
22## Inputs required
23
24- Repo root + target plugin/theme/mu-plugin (path to entrypoint).
25- Desired namespace + version (e.g. `my-plugin/v1`) and routes.
26- Authentication mode (cookie + nonce vs application passwords vs auth plugin).
27- Target WordPress version constraints (if below 7.0, call out).
28
29## Procedure
30
31### 0) Triage and locate REST usage
32
331. Run triage:
34 - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
352. Search for existing REST usage:
36 - `register_rest_route`
37 - `WP_REST_Controller`
38 - `rest_api_init`
39 - `show_in_rest`, `rest_base`, `rest_controller_class`
40
41If this is a full site repo, pick the specific plugin/theme before changing code.
42
43### 1) Choose the right approach
44
45- **Expose CPT/taxonomy in `wp/v2`:**
46 - Use `show_in_rest => true` + `rest_base` if needed.
47 - Optionally provide `rest_controller_class`.
48 - Read `references/custom-content-types.md`.
49- **Custom endpoints:**
50 - Use `register_rest_route()` on `rest_api_init`.
51 - Prefer a controller class (`WP_REST_Controller` subclass) for anything non-trivial.
52 - Read `references/routes-and-endpoints.md` and `references/schema.md`.
53
54### 2) Register routes safely (namespaces, methods, permissions)
55
56- Use a unique namespace `vendor/v1`; avoid `wp/*` unless core.
57- Always provide `permission_callback` (use `__return_true` for public endpoints).
58- Use `WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLE` constants.
59- Return data via `rest_ensure_response()` or `WP_REST_Response`.
60- Return errors via `WP_Error` with an explicit `status`.
61
62Read `references/routes-and-endpoints.md`.
63
64### 3) Validate/sanitize request args
65
66- Define `args` with `type`, `default`, `required`, `validate_callback`, `sanitize_callback`.
67- Prefer JSON Schema validation with `rest_validate_value_from_schema` then `rest_sanitize_value_from_schema`.
68- Never read `$_GET`/`$_POST` directly inside endpoints; use `WP_REST_Request`.
69
70Read `references/schema.md`.
71
72### 4) Responses, fields, and links
73
74- Do **not** remove core fields from default endpoints; add fields instead.
75- Use `register_rest_field` for computed fields; `register_meta` with `show_in_rest` for meta.
76- For `object`/`array` meta, define schema in `show_in_rest.schema`.
77- 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.
78- Add related resource links via `WP_REST_Response::add_link()`.
79
80Read `references/responses-and-fields.md`.
81
82### 5) Authentication and authorization
83
84- For wp-admin/JS: cookie auth + `X-WP-Nonce` (action `wp_rest`).
85- For external clients: application passwords (basic auth) or an auth plugin.
86- Use capability checks in `permission_callback` (authorization), not just “logged in”.
87
88Read `references/authentication.md`.
89
90### 6) Client-facing behavior (discovery, pagination, embeds)
91
92- Ensure discovery works (`Link` header or `<link rel="https://api.w.org/">`).
93- Support `_fields`, `_embed`, `_method`, `_envelope`, pagination headers.
94- Remember `per_page` is capped at 100.
95
96Read `references/discovery-and-params.md`.
97
98## Verification
99
100- `/wp-json/` index includes your namespace.
101- `OPTIONS` on your route returns schema (when provided).
102- Endpoint returns expected data; permission failures return 401/403 as appropriate.
103- CPT/taxonomy routes appear under `wp/v2` when `show_in_rest` is true.
104- Run repo lint/tests and any PHP/JS build steps.
105
106## Failure modes / debugging
107
108- 404: `rest_api_init` not firing, route typo, or permalinks off (use `?rest_route=`).
109- 401/403: missing nonce/auth, or `permission_callback` too strict.
110- `_doing_it_wrong` for missing `permission_callback`: add it (use `__return_true` if public).
111- Invalid params: missing/incorrect `args` schema or validation callbacks.
112- Fields missing: `show_in_rest` false, meta not registered, or CPT lacks `custom-fields` support.
113
114## Escalation
115
116If version support or behavior is unclear, consult the REST API Handbook and core docs before inventing patterns.