Index of every page on this site: llms.txt
All skills
automattic avatar

/wp-rest-api

@48d4aa2 official
by automatticautomattic/agent-skills211 stars
37
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/automattic/agent-skills/wp-rest-api

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈79 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈1.4k more on demand in 6 files.

Description uses 4.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈316 characters, or 4.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

  1. Run triage:
    • node skills/wp-project-triage/scripts/detect_wp_project.mjs
  2. 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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides a set of secure development guidelines and best practices for building and debugging WordPress REST API endpoints. It emphasizes essential security measures such as permission callbacks, nonce validation, and schema-based argument sanitization. No malicious patterns or security risks were identified.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    4/7 files flagged

Signed by skilld at 48d4aa2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Dormantupdated 10 months ago
Other metadata
compatibility
Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI.
  • wordpress
  • rest-api
  • php
  • endpoints
  • authentication
  • schema-validation
  • custom-post-types
  • taxonomies
  • permission-callbacks

README badge

README badge for automattic/agent-skills/wp-rest-api

Registers and debugs WordPress REST API endpoints, routes, and custom fields using register_rest_route, WP_REST_Controller, schema validation, and permission callbacks. Use this when exposing custom post types or taxonomies via REST, adding meta fields to responses, or troubleshooting 401/403/404 errors in WordPress 6.9+.

Generated from the current SKILL.md.

Does this skill work with WordPress versions below 6.9?
The skill targets WordPress 6.9+ (PHP 7.2.24+). If you're on an older version, call out the constraint before proceeding.
What authentication methods does this skill support?
Cookie auth with nonce (for wp-admin/JS), application passwords (basic auth for external clients), or custom auth plugins. The skill guides you to choose the right method based on your use case.
Can I add custom fields to existing REST endpoints without modifying core?
Yes. Use `register_rest_field` for computed fields or `register_meta` with `show_in_rest` for meta. The skill advises against removing core fields; instead, add new ones.
How does this skill handle custom post types and taxonomies?
For built-in endpoints, set `show_in_rest => true` on the post type or taxonomy registration. For full control, provide a custom `rest_controller_class` that extends `WP_REST_Controller`.
What does the skill expect as input before I use it?
You need the repo root and path to your target plugin/theme/mu-plugin, your desired namespace and version (e.g. `my-plugin/v1`), authentication mode, and any WordPress version constraints.

Generated from the current SKILL.md. These answers refresh after source changes.