wp-rest-api
Use when building, extending, or debugging WordPress REST API endpoints/routes: registerrestroute, WPRESTController/controller classes, schema/argument validation, permissioncallback/authentication, response shaping, registerrestfield/registermeta, or exposing CPTs/taxonomies via showinrest.
- Installs
- 5.9K
- Last 24h
- +47
- Trending rank
- #3517
- Security
- Warn
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/wordpress/agent-skills --skill wp-rest-api- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads wp-rest-api automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
- Run triage:
node skills/wp-project-triage/scripts/detect_wp_project.mjs
- Search for existing REST usage:
register_rest_routeWP_REST_Controllerrest_api_initshow_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_baseif needed. - Optionally provide
rest_controller_class. - Read
references/custom-content-types.md.
- Use
- Custom endpoints:
- Use
register_rest_route()onrest_api_init. - Prefer a controller class (
WP_REST_Controllersubclass) for anything non-trivial. - Read
references/routes-and-endpoints.mdandreferences/schema.md.
- Use
2) Register routes safely (namespaces, methods, permissions)
- Use a unique namespace
vendor/v1; avoidwp/*unless core. - Always provide
permission_callback(use__return_truefor public endpoints). - Use
WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLEconstants. - Return data via
rest_ensure_response()orWP_REST_Response. - Return errors via
WP_Errorwith an explicitstatus.
Read references/routes-and-endpoints.md.
3) Validate/sanitize request args
- Define
argswithtype,default,required,validate_callback,sanitize_callback. - Prefer JSON Schema validation with
rest_validate_value_from_schemathenrest_sanitize_value_from_schema. - Never read
$_GET/$_POSTdirectly inside endpoints; useWP_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_fieldfor computed fields;register_metawithshow_in_restfor meta. - For
object/arraymeta, define schema inshow_in_rest.schema. - If you need unfiltered post content (e.g., ToC plugins injecting HTML), request
?context=editto accesscontent.raw(auth required). Pair with_fields=content.rawto 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(actionwp_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 (
Linkheader or<link rel="https://api.w.org/">). - Support
_fields,_embed,_method,_envelope, pagination headers. - Remember
per_pageis capped at 100.
Read references/discovery-and-params.md.
Verification
/wp-json/index includes your namespace.OPTIONSon your route returns schema (when provided).- Endpoint returns expected data; permission failures return 401/403 as appropriate.
- CPT/taxonomy routes appear under
wp/v2whenshow_in_restis true. - Run repo lint/tests and any PHP/JS build steps.
Failure modes / debugging
- 404:
rest_api_initnot firing, route typo, or permalinks off (use?rest_route=). - 401/403: missing nonce/auth, or
permission_callbacktoo strict. _doing_it_wrongfor missingpermission_callback: add it (use__return_trueif public).- Invalid params: missing/incorrect
argsschema or validation callbacks. - Fields missing:
show_in_restfalse, meta not registered, or CPT lackscustom-fieldssupport.
Escalation
If version support or behavior is unclear, consult the REST API Handbook and core docs before inventing patterns.
FAQ
What does the wp-rest-api skill do?
Use when building, extending, or debugging WordPress REST API endpoints/routes: registerrestroute, WPRESTController/controller classes, schema/argument validation, permissioncallback/authentication, response shaping, registerrestfield/registermeta, or exposing CPTs/taxonomies via showinrest.
How do I install wp-rest-api?
Run npx skills add https://github.com/wordpress/agent-skills --skill wp-rest-api in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/wp-rest-api/ (personal) or .claude/skills/wp-rest-api/ (project).
Which AI agents can use wp-rest-api?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is wp-rest-api safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer flagged items to review; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains wp-rest-api?
It is published by wordpress in wordpress/agent-skills, and it is an official skill from the maker of the technology it covers. It has 5,902 recorded installs.
More from wordpress/agent-skills
wp-plugin-development
wordpress/agent-skills
Use when developing WordPress plugins: architecture and hooks, activation/deactivation/uninstall, admin UI and Settings API, data storage, cron/tasks, security (nonces/capabilities/sanitization/escaping), and release packaging.
wp-performance
wordpress/agent-skills
Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification.
wp-block-themes
wordpress/agent-skills
Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching).
wordpress-router
wordpress/agent-skills
Use when the user asks about WordPress codebases (plugins, themes, block themes, Gutenberg blocks, WP core checkouts) and you need to quickly classify the repo and route to the correct workflow/skill (blocks, theme.json, REST API, WP-CLI, performance, security, testing, release packaging).
wp-block-development
wordpress/agent-skills
Use when developing WordPress (Gutenberg) blocks: block.json metadata, registerblocktype(frommetadata), attributes/serialization, supports, dynamic rendering (render.php/rendercallback), deprecations/migrations, viewScript vs viewScriptModule, and @wordpress/scripts/@wordpress/create-block build and test workflows.
wp-wpcli-and-ops
wordpress/agent-skills
Use when working with WP-CLI (wp) for WordPress operations: safe search-replace, db export/import, plugin/theme/user/content management, cron, cache flushing, multisite, and scripting/automation with wp-cli.yml.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.