wp-rest-api/SKILL.md

---

name: wp-rest-api description: "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." compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."

---

Installed helper paths (BB Skills adaptation, 2026-10-04)

Set BB_SKILL_DIR to the absolute directory containing this installed SKILL.md. From the WordPress project root, a default Bash installation can use export BB_SKILL_DIR="$PWD/.agents/skills/wp-rest-api". If installed elsewhere, use that absolute folder. Keep the working directory at your WordPress project root: the detector uses process.cwd() and has no project-path argument. On PowerShell, set $env:BB_SKILL_DIR and substitute that variable for the Bash variable in the command.

The bundled triage helper and six REST references come from the same pinned WordPress commit. Only the helper command path and this setup note were adapted; upstream-original/SKILL.md retains the original instructions. Upstream authorship disclosures are retained verbatim as source-context text, not as additional executable skills. The upstream skill targets WordPress 7.0+ and PHP 7.4.0+; verify your target environment.

BB Skills checked source provenance, package completeness, license notices, helper imports and Node.js syntax. It also recorded 27 synthetic HTTP observations using a hand-authored fixture on WordPress 7.1.2 and PHP 8.3.35. The bundled triage detector, WP-CLI and AI-agent workflow were not executed. The helper reads project files and prints inspection hints; review it before use and avoid sensitive directories. Limits can truncate scans and detected names can be incomplete. Its recommendations are suggestions, not executed commands.

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

1. Run triage:
2. node "$BB_SKILL_DIR/dependencies/wp-project-triage/scripts/detect_wp_project.mjs"
3. Search for existing REST usage:
4. register_rest_route
5. WP_REST_Controller
6. rest_api_init
7. 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.

Bounded native fixture (BB Skills package revision, 2026-10-04)

The examples/ folder contains the hand-authored synthetic plugin, temporary setup, Python HTTP probe, Docker runner and recorded evidence. This fixture exercises selected REST concepts; it is not an AI-client evaluation or a benchmark of the complete upstream skill. It includes a deliberately wrong login-only permission callback as a negative control. Never install that example plugin on a real site. Internal HTTP was used with the WordPress local environment setting; HTTPS transport and a real browser login were not tested. Read examples/README.md before reproducing.