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 · Explainer

What Is WordPress REST API Base URL? Explained

What Is WordPress REST API Base URL? Explained

Short answer

The WordPress REST API base URL is your site address followed by /wp-json/, for example https://example.com/wp-json/. Core routes sit under the wp/v2 namespace. On sites with plain permalinks, use the fallback form with ?rest_route= added to the site address instead.

Key takeaways

  • The default REST base is the site address plus /wp-json/.
  • Core content routes use the wp/v2 namespace.
  • Plain permalinks need the ?rest_route= fallback.
  • Discovery via the api.w.org link shows the real base on any site.
  • Use rest_url in PHP instead of building URLs by hand.

What is the WordPress REST API base URL?

The WordPress REST API base URL is your site address followed by /wp-json/, such as https://example.com/wp-json/, and every REST API route starts from there.

This base URL is the front door to your site's data in JSON format. Apps, headless front ends, mobile apps and the block editor itself all send requests to paths under it.

For the core WordPress content, the routes sit under a namespace called wp/v2. So the posts endpoint is:

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

The REST API Handbook is the official reference. This article explains the base URL, its variations and how to find it on any site.

What are the parts of a REST API URL?

A WordPress REST API URL has four parts: the site address, the /wp-json/ prefix, a namespace such as wp/v2, and a route such as posts or pages.

Here's how a full URL breaks down:

PartExampleWhat it means
Site addresshttps://example.comYour WordPress site
REST prefix/wp-json/The REST API base
Namespacewp/v2Core WordPress routes, version 2
Route/postsThe resource you want
Item ID/123One specific post

Put together, https://example.com/wp-json/wp/v2/posts/123 returns post 123 as JSON.

Plugins add their own namespaces. WooCommerce, for example, uses wc/v3 for its store routes. So a WooCommerce products request goes to /wp-json/wc/v3/products, as shown in the WooCommerce REST API docs.

Opening the base URL on its own, /wp-json/, returns an index listing every namespace and route the site has registered.

Yes, when a site uses plain permalinks, the /wp-json/ path doesn't work, so you use the fallback format with ?rest_route= added to the site address instead.

The fallback looks like this:

https://example.com/?rest_route=/
https://example.com/?rest_route=/wp/v2/posts

The pretty /wp-json/ URL depends on WordPress rewrite rules. Those only work when permalinks are set to anything other than Plain under Settings, then Permalinks. The Permalinks settings documentation explains each option.

The ?rest_route= form always works, which makes it handy for testing. If /wp-json/ returns a 404 but ?rest_route=/ works, your permalinks or server rewrite rules are the problem.

Our guide on fixing permalinks that aren't working walks through the usual causes.

You can also set up permalinks from scratch if they've never been changed.

How do you find a site's REST API base URL?

Look for the link tag or HTTP Link header with rel set to https://api.w.org/ on the site's home page, which WordPress adds to tell clients exactly where its REST API lives.

This is called API discovery. It matters because the base isn't always /wp-json/ at the domain root.

Ways to find it:

  1. Page source. View the source of the home page and search for api.w.org. The link tag holds the base URL.
  2. HTTP headers. Run a HEAD request with curl and look for the Link header.
  3. Just try it. Open the site address followed by /wp-json/ in a browser.

A quick header check from the terminal:

curl -I https://example.com/

The REST API discovery page explains how clients should find the base URL.

How does the base URL change for subdirectories and multisite?

If WordPress lives in a subfolder or is a subdirectory multisite, the base URL includes that path, such as https://example.com/blog/wp-json/.

Common cases:

  • WordPress in a subfolder: https://example.com/blog/wp-json/
  • Subdirectory multisite: each site has its own, such as https://example.com/site2/wp-json/
  • Subdomain multisite: https://site2.example.com/wp-json/
  • WordPress.com hosted sites: WordPress.com also offers its own public API host for sites on its platform

This is why discovery is useful. Hard-coding /wp-json/ at the domain root breaks on sites that don't live at the root.

How do you get the base URL in PHP?

Use rest_url or get_rest_url in your theme or plugin code, which return the correct REST base for the current site and handle permalinks, subfolders and multisite for you.

A simple example:

$base  = rest_url();               // https://example.com/wp-json/
$posts = rest_url( 'wp/v2/posts' ); // https://example.com/wp-json/wp/v2/posts

For multisite, get_rest_url accepts a site ID as its first argument. That returns the base for another site in the network.

The rest_url function reference lists its parameters. Using it instead of building URLs by hand avoids bugs when a site moves or changes its permalink settings.

In JavaScript inside WordPress, the apiFetch package handles the base for you. You pass a path like /wp/v2/posts and it adds the right root.

Can you change the /wp-json/ prefix?

Yes, developers can change it with the rest_url_prefix filter, but it rarely improves security and can break plugins or apps that assume the default.

Example:

add_filter( 'rest_url_prefix', function () {
    return 'api';
} );

After adding it, re-save permalinks so the new rewrite rule takes effect. The base becomes https://example.com/api/.

Think carefully before doing this. Discovery still announces the new base, so it doesn't hide the API. Some tools and plugins hard-code /wp-json/ and will stop working.

If your aim is to restrict access, use authentication and permission checks instead. Our guide on enabling the REST API in WordPress covers access settings.

Why does the REST API base URL return an error?

Errors at the base URL usually come from broken permalinks, a security plugin blocking the API, server rules, or a plugin outputting PHP errors that corrupt the JSON.

Match the error to the cause:

What you seeLikely causeWhere to look
404 Not FoundRewrite rules brokenRe-save permalinks, check .htaccess or Nginx rules
401 or 403Security plugin, firewall or auth rulePlugin settings, host firewall
Invalid JSONPHP warnings or extra outputDebug log, recently changed plugins
Redirect to home pagePlugin or rule redirecting /wp-json/Redirect plugins, server config
TimeoutSlow plugin or server limitsServer error log, host

The block editor depends on the REST API. When it fails, you often see the Updating failed message. Our guide on fixing the invalid JSON response error covers that case.

Site Health also checks the API. If it reports a problem, follow our guide to the REST API error in Site Health.

How do you test the base URL?

Open the base URL in a browser to see the route index, or use curl or an API client such as Postman to send requests and read the JSON reply.

Simple tests:

curl https://example.com/wp-json/
curl https://example.com/wp-json/wp/v2/posts?per_page=2

A working site returns JSON with the site name, description and a list of routes. Public content such as published posts doesn't need authentication.

Write requests, such as creating posts, need authentication. Application Passwords, built into WordPress, are the simplest option for testing. The REST API authentication guide explains each method.

For a fuller walkthrough of requests, see our guide on how to use the WordPress REST API.

When you're ready to add your own routes, read how to create a custom REST API endpoint.

MDN's overview of HTTP request methods is a useful refresher on GET, POST and the others the API uses.

Frequently asked questions

What is the default WordPress REST API URL?

It's your site address followed by /wp-json/. Core content such as posts, pages and users lives under the wp/v2 namespace, so the posts list is at the site address plus /wp-json/wp/v2/posts.

Why does /wp-json/ give a 404 error?

The pretty REST URL depends on rewrite rules. If permalinks are set to Plain or the server ignores rewrite rules, /wp-json/ returns a 404. Re-save permalinks or use the rest_route fallback to test.

Do I need to log in to use the REST API?

Not for public content such as published posts and pages. Creating, editing or deleting content, and reading private data, needs authentication such as Application Passwords or cookie authentication for logged-in users.

Is it safe to leave the REST API base URL public?

Yes, for most sites. The block editor and many plugins rely on it. Permission checks protect private data. If you want to limit access, use authentication rules rather than hiding or renaming the base URL.

How do I find the REST API URL on a WordPress multisite?

Each site in the network has its own base. Subdirectory sites add their path before /wp-json/, while subdomain sites use their own host. Discovery links on each site's home page show the exact base.

Sources

  1. REST API Handbook WordPress Developer Resources
  2. Discovery WordPress REST API Handbook
  3. Authentication WordPress REST API Handbook
  4. rest_url() WordPress Developer Resources
  5. HTTP request methods MDN Web Docs

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.