Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Explainers · Explainer

What Is the WordPress REST API? A Plain Explanation

What Is the WordPress REST API? A Plain Explanation

Short answer

The WordPress REST API is the built-in interface that lets apps read and write your site content as JSON data over HTTP. It has been part of WordPress core since version 4.7, and it is the foundation of the block editor. Public content is readable without a login, while private content needs cookie authentication or an Application Password.

Key takeaways

  • The REST API lets apps read and write WordPress content as JSON data over HTTP.
  • It has been part of WordPress core since version 4.7 and powers the block editor.
  • Your site's API index lives at /wp-json/, with core routes under /wp/v2/.
  • Public content is readable without a login; private content needs authentication.
  • Collections return 10 items per page by default, with a maximum of 100 per request.
  • Application Passwords, added in WordPress 5.6, are the right login method for outside apps.

What is the WordPress REST API?

The WordPress REST API is the built-in interface that lets apps read and write your site content as JSON data over HTTP.

Instead of loading a web page, an app sends a request to a special URL on your site and gets back structured data it can use. The block editor itself works this way: when you save a post, the editor talks to your site through the REST API rather than through a form submit.

The WordPress REST API handbook describes it as an interface for applications to interact with your WordPress site by sending and receiving data as JSON objects, and notes that it is the foundation of the WordPress Block Editor (REST API Handbook).

REST stands for “REpresentational State Transfer,” a set of ideas for treating your site content as objects and collections that apps can request by URL.

When did the WordPress REST API arrive?

The REST API became part of WordPress core in version 4.7, released on December 6, 2016.

The release announcement states that WordPress 4.7 comes with REST API endpoints for posts, comments, terms, users, meta, and settings (WordPress 4.7 “Vaughan”). Before that, remote access to WordPress content meant XML-RPC, an older system that still ships in core for older clients.

Since 4.7, the API has grown with every release. Application Passwords arrived in WordPress 5.6, batch requests and a search route came later, and Site Health moved its async checks to the REST API, according to the same changelog (Changelog).

How do you find your site's REST API?

Open your site address followed by /wp-json/ in a browser, and you will see a JSON index of every route.

The handbook key concepts page explains that a GET request to /wp-json/ returns a JSON response showing what routes are available and what endpoints sit inside each route (Key Concepts). That index is the fastest way to confirm the API is working on your site.

If your site uses plain permalinks, the same index answers at ?rest_route=/ instead. The handbook notes that a 404 on /wp-json/ usually means pretty permalinks are off or the rewrite rules are stale, and trying the rest_route form is the fix (Key Concepts).

What is a route and what is an endpoint?

A route is a URL pattern, and an endpoint is that route combined with one HTTP method.

The handbook defines it plainly: a route is a URI which can be mapped to different HTTP methods, and the mapping of one HTTP method to a route is an endpoint (Key Concepts).

The route wp-json/wp/v2/posts has a GET endpoint that returns a list of posts and a POST endpoint that accepts authenticated requests to create new posts.

Core routes live under the wp/v2 namespace. The table below lists the ones most apps use, with what an unauthenticated request can read.

RouteWhat it returnsWithout login
/wp/v2/postsPosts, 10 per page by defaultPublished posts only
/wp/v2/pagesPagesPublished pages only
/wp/v2/mediaAttachmentsReadable
/wp/v2/categories, /wp/v2/tagsTaxonomy termsReadable
/wp/v2/commentsCommentsApproved comments only
/wp/v2/usersUsersOnly users with published posts
/wp/v2/searchSearch across post typesReadable
/wp/v2/settingsSite settingsNeeds login and permission

What can the public read, and what needs a login?

Public content is generally readable without a login, while private content needs authentication.

The handbook states the rule directly: content that is public on your site is generally publicly accessible via the REST API, while private content, password-protected content, internal users, custom post types, and metadata are only available with authentication (REST API Handbook). Drafts, scheduled posts, and site settings never show up for anonymous requests.

That rule is also why a common Site Health warning about the REST API matters. When the API cannot be reached, the block editor and many plugins lose features, and our guide to fixing the REST API error in Site Health walks through the usual causes.

How does authentication work?

There are two main methods: cookie authentication for code running inside WordPress, and Application Passwords for outside apps.

Cookie authentication is the standard method included with WordPress, and it works when you are logged into the dashboard, according to the handbook authentication page (Authentication). Requests from inside WordPress also send a nonce, a one-time value passed in the X-WP-Nonce header, which stops other sites from forcing your browser to act on their behalf.

Application Passwords shipped with WordPress 5.6 and are generated from the user edit screen in the admin area. The handbook notes they can be passed with REST API requests served over HTTPS using Basic Auth, and gives a curl example that fetches users with context=edit (Authentication).

They are the right choice for scripts, mobile apps, and automation tools, because you can revoke one password without changing your real password.

How do you page through results?

Collections return 10 items per page by default, and you can ask for up to 100 per request.

The handbook pagination page explains that API endpoints default to a limited number of items per request, the same way a WordPress archive defaults to 10 posts per page (Pagination). The per_page parameter accepts an integer from 1 to 100, and page picks which page of results to return.

Two response headers tell you how much data exists: X-WP-Total gives the total number of records, and X-WP-TotalPages gives the total number of pages. The handbook notes that per_page is capped at 100 records, because large queries can hurt site performance, so fetching more means making several requests (Pagination).

How do you test a REST API request?

Start with a plain GET in your browser, then move to curl when you need to send credentials.

Open /wp-json/wp/v2/posts on your own site and you should see your latest published posts as JSON. If that works, the API is up and the public routes are open.

For a request that needs a login, the handbook authentication page shows the pattern: curl --user "USERNAME:PASSWORD" https://HOSTNAME/wp-json/wp/v2/users?context=edit, where the username and password are an Application Password pair (Authentication).

A 401 reply means the request needs authentication, and a 403 means the logged-in user lacks the capability for that action. Both are normal guardrails, not bugs, and they confirm the permission checks are working.

What is the REST API used for?

It powers the block editor, headless sites, mobile apps, and automation tools that publish into WordPress.

The handbook lists the main uses: building a new admin experience as a plugin, building a new interactive front end, or bringing WordPress content into separate applications (REST API Handbook). Any programming language that can make HTTP requests and interpret JSON can use it, from PHP and Node.js to Swift and Kotlin.

The handbook also notes that the REST API gives a more predictable way to interact with your site than admin-ajax, the older endpoint that handles dashboard actions. All WordPress AJAX requests must be sent to wp-admin/admin-ajax.php, according to the WordPress AJAX handbook (AJAX in Plugins).

A headless site is the clearest example. WordPress stores and manages the content, while a separate front end, often built with JavaScript, fetches posts through /wp/v2/posts and renders them.

The same pattern drives mobile apps and tools that publish scheduled posts from outside the dashboard.

Related WordPress APIs build on the same idea of structured data inside WordPress, such as the Interactivity API.

The HTML API is covered in a separate guide on this site.

What mistakes should you avoid?

The most common mistakes are exposing private data, skipping permission checks, and trusting the API without testing it.

Custom post types and custom fields do not appear in the API unless they are registered with show_in_rest set to true, as the handbook changelog notes for taxonomies (Changelog). If your content is missing from the API, that flag is the first thing to check.

When you write your own route with register_rest_route, always give it a real permission_callback. Since WordPress 5.5, leaving it out triggers a “doing it wrong” notice when debugging is on, according to the handbook changelog (Changelog).

The Make WordPress Core dev note for 5.5 explains why: the REST API treats routes without a permission callback as public (REST API changes in WordPress 5.5). A route that writes data and allows anyone to call it is a security hole.

Finally, do not assume the API is healthy just because the site loads. Open /wp-json/ and check for a JSON index, and if it returns an error, see our guide to fixing the “updating failed, the response is not a valid JSON response” error, which covers the same class of problem.

Frequently asked questions

Is the REST API enabled by default on WordPress?

Yes, on any site running WordPress 4.7 or later, which covers nearly every live site today. You can confirm it by opening yoursite.com/wp-json/ in a browser: a JSON index of routes means the API is working. If it returns a 404, pretty permalinks may be off or the rewrite rules may be stale.

What is the difference between the REST API and admin-ajax.php?

The API is a general interface for reading and writing all WordPress content, while admin-ajax.php is the older endpoint that handles dashboard actions such as Heartbeat and form submissions. The REST API is the recommended way to build new features, because its routes, schemas, and permissions are structured and documented.

How do I create an Application Password?

They are generated on the user edit screen in the admin area, under Application Passwords. Each password works like a separate login for one app or script, and you can revoke it at any time without changing your real password. Always use them over HTTPS, never over plain HTTP.

Can anyone read my draft posts through the REST API?

No. Drafts, scheduled posts, private content, and site settings are only available to logged-in users with the right capability. Anonymous requests can only see published posts, pages, approved comments, and other public content. A plugin can change what is public, so check your settings if you see something unexpected.

How do I fetch more than 10 posts at a time?

Use the per_page parameter, up to 100 items per request, and the page parameter to move through the results. The X-WP-Total and X-WP-TotalPages response headers tell you how many records and pages exist in total. Fetching more than 100 items means making several requests and combining them.

Sources

  1. REST API Handbook WordPress Developer Resources
  2. Key Concepts WordPress Developer Resources
  3. Authentication WordPress Developer Resources
  4. Pagination WordPress Developer Resources
  5. Changelog WordPress Developer Resources
  6. WordPress 4.7 “Vaughan” WordPress.org
  7. AJAX in Plugins WordPress Codex
  8. REST API changes in WordPress 5.5 Make WordPress Core

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.