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

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.

wp-rest-api

NPX Install

Tags

SKILL.md Content

WP REST API

When to use

Inputs required

Procedure

0) Triage and locate REST usage

1) Choose the right approach

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

3) Validate/sanitize request args

4) Responses, fields, and links

5) Authentication and authorization

6) Client-facing behavior (discovery, pagination, embeds)

Verification

Failure modes / debugging

Escalation