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

Developer · Guide

How to Use the WordPress REST API

How to Use the WordPress REST API

Short answer

To use the WordPress REST API, send HTTP requests to your site at /wp-json/, with core routes under wp/v2, such as GET /wp/v2/posts to read posts. Filter and page lists with search, categories, page, and per_page, and create or update content with POST calls. Sign in with a cookie and wp_rest nonce inside WordPress, or with an application password and Basic Auth over HTTPS from outside it.

Key takeaways

  • The REST API lives at /wp-json/, with core routes under the wp/v2 namespace.
  • GET reads content, POST creates or updates it, and DELETE removes it from a route.
  • per_page is capped at 100, and X-WP-Total and X-WP-TotalPages show how much data is left.
  • Cookie calls use a wp_rest nonce; outside calls use an application password with Basic Auth over HTTPS.
  • Custom routes need register_rest_route plus a permission_callback, or WordPress raises a notice.

What is the WordPress REST API?

The WordPress REST API is a JSON interface built into WordPress that lets any app read and write your site content over HTTP.

The REST API gives a way to match URIs to resources in a WordPress install. Developer.WordPress.org states that by default, with pretty permalinks on, the API lives at /wp-json/ on your site (checked November 2026).

Open https://example.com/wp-json/ in a browser to see the index. Developer.WordPress.org states that the index gives data about what routes are open for that install, with the HTTP methods each one supports (checked November 2026).

A route is the name you use to reach an endpoint, and an endpoint is one HTTP method on that route. Developer.WordPress.org states that a route can hold more than one endpoint, and the HTTP verb picks which one runs (checked November 2026).

For the URL https://example.com/wp-json/wp/v2/posts/123, the route is wp/v2/posts/123. Developer.WordPress.org states that this route has 3 endpoints: GET reads the post, PUT updates it, and DELETE deletes it (checked November 2026).

Core routes live under the wp/v2 namespace. Developer.WordPress.org states that you must not place anything into the wp namespace unless you plan to merge it into core (checked November 2026).

What do you need before you start?

You need a WordPress site, a way to send HTTP requests, and HTTPS turned on before you send any password or token.

A browser is enough for public reads. Type a route such as /wp-json/wp/v2/posts after your domain, and the browser shows the JSON reply.

For writes and for scripts, use curl from the command line or a small script in any language. The examples below use curl because it shows the method, the address, and the data in one line.

Turn on HTTPS before you authenticate. Developer.WordPress.org states that application passwords are available when requests are served over HTTPS (checked November 2026).

Check your PHP version as part of the setup. WordPress.org states that WordPress recommends PHP 8.3 or greater, with HTTPS support (checked November 2026).

A guide on how to fix the REST API error in Site Health covers the checks to run when the API does not answer at all, such as a blocked route or a failing loopback request.

How do you read posts and pages?

Read content with GET calls to the core routes, starting with the posts list and then one item by ID.

List the latest posts with this call:

curl https://example.com/wp-json/wp/v2/posts

Developer.WordPress.org gives this same call as the way to query the posts endpoint (checked November 2026).

Read one post by its ID:

curl https://example.com/wp-json/wp/v2/posts/123

Developer.WordPress.org gives this call for one post record, with the ID in the route (checked November 2026).

The reply is JSON with fields such as id, date, slug, title, and content. Developer.WordPress.org states that the schema lists all the fields in a post record, and that a reply holds those fields unless a filter trims them (checked November 2026).

Without pretty permalinks, the same route uses a query value instead. Developer.WordPress.org states that the full URL is then https://example.com/?rest_route=/wp/v2/posts/123 (checked November 2026).

RouteWhat it returnsNeeds sign-in?
GET /wp/v2/postsPublished posts, 10 per page by defaultNo
GET /wp/v2/posts/123One published postNo
GET /wp/v2/pagesPublished pagesNo
GET /wp/v2/mediaMedia itemsNo
GET /wp/v2/categoriesCategory termsNo
GET /wp/v2/commentsCommentsNo
GET /wp/v2/usersUser listNo
GET /wp/v2/users/meYour own user recordYes

Only published content shows to signed-out callers. Drafts, private posts, and the edit context need a signed-in user with the right role.

How do you filter, search, and page through results?

Use query values to narrow a list, then page through it with page and per_page instead of pulling everything at once.

Filter posts by one category with this call:

curl "https://example.com/wp-json/wp/v2/posts?categories=5"

Search posts for a word with this call:

curl "https://example.com/wp-json/wp/v2/posts?search=woocommerce"

Page through a list with page and per_page. Developer.WordPress.org states that ?page=2 asks for the second page of results, and that you can reach every post by fetching page 1, then page 2, and so on (checked November 2026).

per_page takes a whole number from 1 to 100. Developer.WordPress.org states that large queries can hurt site speed, so per_page is capped at 100 records (checked November 2026).

The reply headers tell you how much data is left. Developer.WordPress.org states that the API returns X-WP-Total with the total record count and X-WP-TotalPages with the total page count (checked November 2026).

Sort a list with order and orderby. Developer.WordPress.org states that order takes asc or desc, that all native lists return in falling date order by default, and that posts accept orderby values of date, relevance, id, include, title, and slug (checked November 2026).

How do you create and update content?

Create content with POST to a list route, update it with POST to one item route, and delete it with DELETE to that same route.

Create a draft post with this call, using your own domain and login:

curl -X POST https://example.com/wp-json/wp/v2/posts \
  --user "USERNAME:APPLICATION_PASSWORD" \
  -d '{"title":"Hello REST API","status":"draft","content":"First post through the API."}'

Developer.WordPress.org gives the POST /wp/v2/posts endpoint for making a new post record (checked November 2026).

Change the title of post 123 with this call:

curl -X POST https://example.com/wp-json/wp/v2/posts/123 \
  --user "USERNAME:APPLICATION_PASSWORD" \
  -d '{"title":"My New Title"}'

Developer.WordPress.org gives this same call shape for changing a post title through the API (checked November 2026).

Delete post 123 with this call:

curl -X DELETE https://example.com/wp-json/wp/v2/posts/123 \
  --user "USERNAME:APPLICATION_PASSWORD"

A delete without force moves the post to trash, while force=true skips trash and deletes it at once. Developer.WordPress.org states that force sets whether to skip trash and force deletion (checked November 2026).

Send the data as JSON with the right content type when you write from code. A call with the wrong type can fail or save the fields as plain text instead of the values you meant.

How do you authenticate a request?

Sign in with a cookie and a nonce inside WordPress, or with an application password and Basic Auth from outside it.

Cookie auth is the standard method inside WordPress. Developer.WordPress.org states that when you log in to the dashboard, the cookies are set for you, so code running inside WordPress needs only a signed-in user (checked November 2026).

For cookie calls, the API uses a nonce with the action wp_rest. Developer.WordPress.org states that the nonce can be passed through the _wpnonce data value or the X-WP-Nonce header (checked November 2026).

With no nonce, the API treats the call as signed out. Developer.WordPress.org states that with no nonce given, the API sets the current user to 0, turning the request into an unauthenticated one (checked November 2026).

From outside the site, use an application password. Developer.WordPress.org states that as of WordPress 5.6, application passwords can be made from the Edit User page (checked November 2026).

Send the username and the application password with Basic Auth over HTTPS:

curl --user "USERNAME:PASSWORD" https://example.com/wp-json/wp/v2/users?context=edit

Developer.WordPress.org gives this curl example for reading users with the edit context (checked November 2026).

Basic Auth sends the pair encoded with Base64. RFC 7617 states that the scheme sends user-id and password pairs encoded with Base64, and that it is not safe without a secure system such as TLS (checked November 2026).

Make WordPress Core states that an application password is 24 characters long, made only of upper-case, lower-case, and numeric characters (checked November 2026).

A companion guide on application passwords in this same batch explains the dashboard steps for making one. A guide on how to add custom user roles in WordPress explains how to give the API user the lowest role that covers the job.

How do you add your own endpoint?

Register a route with register_rest_route() on the rest_api_init hook, and always add a permission_callback that checks what the caller may do.

Register routes on rest_api_init so the work runs only when the API loads. Developer.WordPress.org states that register_rest_route() should be called in a callback on rest_api_init to avoid extra work when the API is not loaded (checked November 2026).

A short example registers a route under your own namespace:

add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/author/([0-9]+)', array(
        'methods'  => 'GET',
        'callback' => 'my_awesome_func',
    ) );
} );

Developer.WordPress.org gives this example with the namespace myplugin/v1 and a route that takes an author ID as a number (checked November 2026).

Namespaces follow the pattern of vendor then version, such as myplugin/v1. Developer.WordPress.org states that namespaces stop two plugins from adding a route with the same name (checked November 2026).

Add a permission_callback to every endpoint. Developer.WordPress.org states that the callback should return true, false, or a WP_Error, and that a false result stops the request with a default error (checked November 2026).

Since WordPress 5.5, a route with no permission_callback gets a _doing_it_wrong notice. Developer.WordPress.org states that for routes meant to be public, you should use __return_true as the permission callback (checked November 2026).

Return data, a WP_REST_Response, or a WP_Error from the callback. Developer.WordPress.org states that the return value is turned into JSON, and that a WP_Error passes its error data to the client (checked November 2026).

A guide on how to create a custom REST API endpoint in WordPress walks through the full controller pattern used by core routes.

What mistakes should you avoid?

Avoid public routes with no permission check, plain HTTP calls with a password, and hard-coded API addresses in your code.

Never leave out permission_callback. Without it, a route that was meant for editors may answer any caller, and since WordPress 5.5 the missing callback also raises a notice.

Do not use the Basic Authentication plugin on a live site. Developer.WordPress.org states that the plugin should only be used for development and testing, not in a live setting, and that application passwords are preferred (checked November 2026).

Do not hard-code /wp-json/ in your code. Developer.WordPress.org states that on sites without pretty permalinks the route is added to the URL as the rest_route value instead, so a fixed /wp-json/ address fails on those sites (checked November 2026).

Do not call wp_send_json() inside a REST callback. Developer.WordPress.org states that as of WordPress 5.5, a _doing_it_wrong notice is given when the wp_send_json() family runs during a REST API request (checked November 2026).

Do not ask for more than 100 items per page. The cap is firm, so loop through pages with page and per_page=100 instead of asking for the whole list at once.

A guide on how to make AJAX requests in WordPress covers the admin-ajax path for page features that do not need a REST route.

How do you check that it worked?

Check the API in three steps: read the index, read a public list, and then run one signed-in write.

Open https://example.com/wp-json/ with your own domain in place of example.com. A JSON index with a namespaces list means the API answers.

Call GET /wp/v2/posts next. A 200 reply with a JSON list of published posts means the core routes work and the read path is open.

Then run one signed-in write, such as making a draft post. A 201 reply with the new post ID means the sign-in, the role, and the write path all work.

A 401 reply means the login failed, so check the username and the application password. A 403 reply means the sign-in worked but the role may not run that route, so check the role or use a route it may use.

A guide on how to run a WordPress security audit covers how to review which users and keys may call the API after you have it working.

Frequently asked questions

Do I need to sign in to read content through the API?

No. Published posts, pages, and media can be read without signing in. Drafts, private posts, and the edit context need a signed-in user, and any write call needs sign-in plus the right role.

How do I get more than 100 posts from the API?

Use page and per_page values, such as /wp/v2/posts?per_page=100&page=2. The per_page cap is 100, and the X-WP-Total and X-WP-TotalPages headers tell you how many records and pages exist in total.

What if my site uses plain permalinks?

For a plain-permalink site, add the route as a query value, such as /?rest_route=/wp/v2/posts. The route is the same, only the address form changes, so build addresses from the site settings instead of hard-coding /wp-json/.

Can I add my own endpoints to the API?

Yes, with register_rest_route on the rest_api_init hook. Give it your own namespace such as myplugin/v1, a callback, and a permission_callback that checks what the caller may do. Since WordPress 5.5, a missing permission callback raises a notice.

Why does my API call return 401 or 403?

A 401 means the login failed, so check the username and application password. A 403 means the sign-in worked but the role may not run that route, so check the role or use a route it may use. A rest_forbidden error points to the permission callback.

Can I use the Basic Authentication plugin on a live site?

No. The Basic Authentication plugin sends your real username and password with every call and is meant for development and testing only. Use application passwords over HTTPS for live sites and scripts.

Sources

  1. Routes and Endpoints WordPress Developer Resources
  2. Authentication (REST API Handbook) WordPress Developer Resources
  3. Pagination WordPress Developer Resources
  4. Adding Custom Endpoints WordPress Developer Resources
  5. Posts (REST API Reference) WordPress Developer Resources
  6. RFC 7617: The Basic HTTP Authentication Scheme IETF
  7. Application Passwords: Integration Guide 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.