Agent-skills wp-rest-api

Name: wp-rest-api
Author: WordPress

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.

install

source · Clone the upstream repo

git clone https://github.com/WordPress/agent-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/WordPress/agent-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/wp-rest-api" ~/.claude/skills/wordpress-agent-skills-wp-rest-api && rm -rf "$T"

manifest: skills/wp-rest-api/SKILL.md

source content

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.