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

).

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.