How to Use the WordPress REST API
The WordPress REST API allows applications and services to communicate with WordPress using standard HTTP requests. Instead of interacting with WordPress only through the traditional dashboard, developers can retrieve, create, update, and delete WordPress data programmatically.
This makes WordPress much more flexible. A WordPress website can provide content to mobile applications, JavaScript frontends, external services, custom dashboards, and other websites.
In this guide, you’ll learn what the WordPress REST API is, how to access API endpoints, retrieve posts, work with pages and users, make authenticated requests, create custom endpoints, and troubleshoot common REST API problems.
What Is the WordPress REST API?
The WordPress REST API is an interface that allows external applications to interact with WordPress data through HTTP requests.
For example, a request such as:
https://example.com/wp-json/wp/v2/postscan return WordPress posts in JSON format.
The API uses common HTTP methods:
| HTTP Method | Typical Purpose |
|---|---|
| GET | Retrieve data |
| POST | Create data |
| PUT | Replace data |
| PATCH | Update data |
| DELETE | Delete data |
WordPress primarily uses REST routes and endpoints to determine which data or functionality a request should access.
Why Use the WordPress REST API?
The REST API is useful when WordPress needs to communicate with another application.
Common use cases include:
- Mobile applications
- React applications
- Vue.js websites
- Next.js frontends
- Custom dashboards
- Headless WordPress websites
- External content systems
- Automated publishing tools
- Third-party integrations
- JavaScript-powered interfaces
- Custom WordPress plugins
For example, a developer could use WordPress as a content management system while displaying the content through a separate frontend application.
Understanding REST API Endpoints
An API endpoint is a URL that provides access to a particular resource.
A standard WordPress posts endpoint looks like:
/wp-json/wp/v2/postsFor a website located at:
https://example.comthe complete endpoint becomes:
https://example.com/wp-json/wp/v2/postsWordPress returns the requested information as JSON.
How to Access the WordPress REST API
The easiest way to test the REST API is to open an endpoint in your browser.
For example:
https://example.com/wp-json/wp/v2/postsReplace example.com with your WordPress domain.
If the REST API is available, WordPress will return JSON data containing posts.
A response may look similar to:
[
{
"id": 101,
"date": "2026-09-30T10:00:00",
"slug": "example-post",
"status": "publish",
"type": "post",
"title": {
"rendered": "Example Post"
}
}
]The actual response contains considerably more information.
What Is JSON?
JSON stands for JavaScript Object Notation.
It is a lightweight format commonly used for exchanging data between applications.
For example:
{
"id": 101,
"title": "My WordPress Post",
"status": "publish"
}A JavaScript application can read this information and display it on a webpage.
Common WordPress REST API Endpoints
WordPress provides many built-in REST API routes.
Some commonly used endpoints include:
/wp-json/wp/v2/posts
/wp-json/wp/v2/pages
/wp-json/wp/v2/media
/wp-json/wp/v2/categories
/wp-json/wp/v2/tags
/wp-json/wp/v2/usersFor example:
Posts
https://example.com/wp-json/wp/v2/postsPages
https://example.com/wp-json/wp/v2/pagesCategories
https://example.com/wp-json/wp/v2/categoriesTags
https://example.com/wp-json/wp/v2/tagsMedia
https://example.com/wp-json/wp/v2/mediaSome endpoints require authentication or appropriate permissions.
How to Retrieve a Specific Post
If you know a post’s ID, you can request it directly.
For example:
https://example.com/wp-json/wp/v2/posts/101The final number represents the post ID.
The API returns information about that specific post.
How to Retrieve Posts With Parameters
WordPress REST API endpoints support query parameters.
For example:
/wp-json/wp/v2/posts?per_page=5This requests up to five posts.
You can also request posts from a particular page:
/wp-json/wp/v2/posts?page=2&per_page=10This is useful when building pagination into an application.
Search WordPress Posts Using the REST API
You can search posts using the search parameter:
/wp-json/wp/v2/posts?search=hostingThis can return posts matching the search term.
For example:
https://example.com/wp-json/wp/v2/posts?search=hostingThis functionality can be useful for creating custom search interfaces.
Retrieve Posts by Category
The REST API can filter posts by category.
For example:
/wp-json/wp/v2/posts?categories=5Here, 5 represents the category ID.
You can combine multiple parameters:
/wp-json/wp/v2/posts?categories=5&per_page=10Retrieve Posts by Tag
You can similarly filter posts using a tag ID:
/wp-json/wp/v2/posts?tags=12You can combine filters with pagination and ordering.
Sort REST API Results
The REST API provides parameters for ordering results.
For example:
/wp-json/wp/v2/posts?orderby=date&order=descThis requests posts ordered by date in descending order.
Other supported ordering options depend on the endpoint.
Using the REST API With JavaScript
One of the most common uses of the WordPress REST API is retrieving WordPress content with JavaScript.
For example:
fetch('https://example.com/wp-json/wp/v2/posts')
.then(response => response.json())
.then(posts => {
console.log(posts);
})
.catch(error => {
console.error('API Error:', error);
});The fetch() function sends the HTTP request.
The response is then converted into JSON.
Display WordPress Posts With JavaScript
You can also use the returned data to generate HTML.
Example:
fetch('https://example.com/wp-json/wp/v2/posts?per_page=5')
.then(response => response.json())
.then(posts => {
const container = document.getElementById('posts');
posts.forEach(post => {
const article = document.createElement('article');
article.innerHTML = `
<h2>${post.title.rendered}</h2>
<div>${post.excerpt.rendered}</div>
`;
container.appendChild(article);
});
});HTML:
<div id="posts"></div>This creates a simple JavaScript-powered WordPress post listing.
When inserting API-provided HTML into a page, make sure the data source is trusted and consider appropriate sanitization and rendering practices.
Using the WordPress REST API With PHP
PHP applications can also request REST API data.
For example:
$response = wp_remote_get(
'https://example.com/wp-json/wp/v2/posts'
);
if (is_wp_error($response)) {
return;
}
$body = wp_remote_retrieve_body($response);
$posts = json_decode($body, true);WordPress’s HTTP API provides functions such as wp_remote_get() for making HTTP requests.
You can then process the returned data in PHP.
Understanding Authentication
Public WordPress content can often be retrieved without authentication.
However, operations that modify WordPress data generally require authentication and appropriate permissions.
For example:
- Creating posts
- Updating posts
- Deleting posts
- Uploading media
- Modifying settings
- Accessing protected information
WordPress must be able to determine who is making the request and whether that user is authorized to perform the requested operation.
WordPress Application Passwords
For external applications that need to authenticate with a WordPress site, Application Passwords provide a built-in authentication mechanism for supported WordPress installations.
Application Passwords are different from a user’s normal WordPress login password.
They are intended for programmatic access.
In WordPress, an administrator or eligible user can manage application passwords from the user’s profile area.
An application password should be treated like a credential and should never be published in JavaScript, Git repositories, screenshots, or public code.
Making an Authenticated Request
For example, a PHP application can use Basic Authentication with an application password over HTTPS.
A simplified example is:
$username = 'api-user';
$application_password = 'xxxx xxxx xxxx xxxx xxxx xxxx';
$response = wp_remote_post(
'https://example.com/wp-json/wp/v2/posts',
array(
'headers' => array(
'Authorization' => 'Basic ' . base64_encode(
$username . ':' . $application_password
),
'Content-Type' => 'application/json',
),
'body' => wp_json_encode(
array(
'title' => 'New API Post',
'content' => 'This post was created through the REST API.',
'status' => 'draft',
)
),
)
);Always use HTTPS when sending credentials.
Never place real credentials directly into publicly accessible frontend JavaScript.
Create a WordPress Post With the REST API
An authenticated POST request can create a new post.
The request is sent to:
/wp-json/wp/v2/postsThe request body might contain:
{
"title": "My New Post",
"content": "This content was created through the REST API.",
"status": "draft"
}The status can be set according to the permissions and workflow required.
For example:
draftcan be useful when content should be reviewed before publication.
Update an Existing Post
To update an existing post, send an authenticated request to its endpoint.
For example:
/wp-json/wp/v2/posts/101A request body could contain:
{
"title": "Updated Post Title"
}The server updates the post if the authenticated user has sufficient permissions.
Delete a Post
An authenticated DELETE request can be used to remove a post.
For example:
/wp-json/wp/v2/posts/101with the HTTP method:
DELETESome WordPress resources provide additional options for moving content to the trash rather than permanently deleting it.
Always test deletion operations carefully.
Working With Media
The REST API also provides a media endpoint:
/wp-json/wp/v2/mediaThis can be used to retrieve media library items and, with appropriate authentication, upload media.
Media can then be associated with posts.
For example, a custom publishing application could:
- Upload an image.
- Receive the media ID.
- Create a post.
- Assign the image as the featured media.
- Publish or save the post.
This is useful for automated publishing workflows.
WordPress REST API Pagination
REST API responses are paginated.
For example:
/wp-json/wp/v2/posts?per_page=10&page=2requests the second page of results.
WordPress also provides pagination information through response headers.
Common headers include:
X-WP-Total
X-WP-TotalPagesThese can help applications determine how many results and pages are available.
Create a Custom REST API Endpoint
WordPress allows developers to register their own REST API routes.
A simple example:
function ehostpiya_register_api_route() {
register_rest_route(
'ehostpiya/v1',
'/message',
array(
'methods' => 'GET',
'callback' => 'ehostpiya_api_message',
)
);
}
add_action('rest_api_init', 'ehostpiya_register_api_route');
function ehostpiya_api_message() {
return array(
'message' => 'Hello from the custom REST API endpoint.',
);
}The endpoint becomes:
/wp-json/ehostpiya/v1/messageA request might look like:
https://example.com/wp-json/ehostpiya/v1/messageThe API could return:
{
"message": "Hello from the custom REST API endpoint."
}Why Use API Namespaces?
In this example:
ehostpiya/v1is the namespace.
Namespaces generally contain:
- A unique project or plugin identifier
- An API version
For example:
myplugin/v1When the API changes significantly, you can introduce another version:
myplugin/v2Versioning can help maintain compatibility for applications using the older API.
Add Permission Checks to Custom Endpoints
Custom endpoints should not automatically expose sensitive functionality.
For example:
'permission_callback' => function () {
return current_user_can('manage_options');
},A complete example:
function ehostpiya_register_private_route() {
register_rest_route(
'ehostpiya/v1',
'/settings',
array(
'methods' => 'GET',
'callback' => 'ehostpiya_get_settings',
'permission_callback' => function () {
return current_user_can('manage_options');
},
)
);
}
add_action('rest_api_init', 'ehostpiya_register_private_route');The permission callback determines who can access the endpoint.
Avoid exposing private information through publicly accessible API routes.
Validate Custom REST API Parameters
Custom endpoints may accept parameters.
For example:
'args' => array(
'id' => array(
'required' => true,
'validate_callback' => function ($value) {
return is_numeric($value);
},
),
),Validation helps ensure that incoming values meet the expected requirements before processing them.
REST API and Headless WordPress
The REST API makes it possible to use WordPress as a headless CMS.
In a traditional WordPress installation:
WordPress
↓
WordPress Theme
↓
WebsiteWith a headless architecture:
WordPress
↓
REST API
↓
React / Vue / Next.js / Mobile App
↓
FrontendWordPress manages the content while another application controls the presentation layer.
REST API and Custom Post Types
Custom post types can also be exposed through the REST API.
When registering a custom post type, developers can enable REST API support using:
'show_in_rest' => true,For example:
register_post_type(
'services',
array(
'public' => true,
'show_in_rest' => true,
'label' => 'Services',
)
);The custom post type can then be available through a REST endpoint such as:
/wp-json/wp/v2/servicesThe exact route depends on the post type’s configuration.
How to Check Whether the REST API Is Working
You can test the API using:
Browser
Open:
https://example.com/wp-json/Command Line
Using cURL:
curl https://example.com/wp-json/wp/v2/postsJavaScript
fetch('https://example.com/wp-json/wp/v2/posts')
.then(response => response.json())
.then(data => console.log(data));API Testing Tools
Tools designed for HTTP API testing can also be used to inspect:
- Request methods
- Headers
- Authentication
- Parameters
- JSON responses
- HTTP status codes
Common WordPress REST API Errors
404 Not Found
A 404 response can occur when:
- The endpoint is incorrect.
- The route does not exist.
- A custom endpoint was registered incorrectly.
- Rewrite rules need to be refreshed.
- A security or server configuration is interfering.
Check the endpoint carefully.
401 Unauthorized
A 401 response generally indicates that authentication is missing or invalid.
Check:
- Username
- Application Password
- Authorization header
- HTTPS configuration
- Authentication method
403 Forbidden
A 403 response commonly indicates that the request is understood but the current user does not have permission to perform the operation.
Check the user’s capabilities and the endpoint’s permission rules.
400 Bad Request
A 400 response can indicate invalid request data.
Check:
- JSON formatting
- Required parameters
- Parameter values
- Request headers
- Endpoint requirements
REST API Security Best Practices
The REST API should be treated like any other application interface.
Follow these practices:
Use HTTPS
Never send authentication credentials over an unencrypted HTTP connection.
Protect Credentials
Do not place application passwords inside public JavaScript.
Use Least Privilege
Give API users only the permissions they actually need.
Validate Input
Validate parameters before processing them.
Escape Output
Escape dynamic data when it is rendered into HTML or another context.
Add Permission Checks
Custom endpoints should use appropriate permission_callback logic.
Avoid Exposing Sensitive Information
Do not return passwords, private tokens, internal configuration values, or unnecessary personal information through public endpoints.
Monitor API Activity
If your website receives significant API traffic, monitor server logs and application behavior for unusual requests.
WordPress REST API Performance Tips
API requests can consume server resources, particularly when applications repeatedly request large datasets.
Consider the following practices:
- Request only the data you need.
- Use pagination.
- Limit
per_pagevalues. - Avoid unnecessary repeated requests.
- Cache appropriate API responses.
- Optimize database queries in custom endpoints.
- Avoid loading unnecessary plugins or data.
- Use efficient frontend request patterns.
For example, instead of retrieving hundreds of posts at once:
/wp-json/wp/v2/posts?per_page=100consider retrieving smaller pages:
/wp-json/wp/v2/posts?per_page=10&page=1and then requesting additional pages when necessary.
REST API vs WordPress Admin
The WordPress REST API and WordPress admin dashboard serve different purposes.
| Feature | WordPress Admin | REST API |
|---|---|---|
| Human interface | Yes | No |
| Programmatic access | Limited | Yes |
| JSON responses | Not the primary interface | Yes |
| Mobile applications | Not designed for this | Suitable |
| JavaScript applications | Limited | Excellent |
| Automated integrations | Limited | Excellent |
| Content management | Yes | Yes, through API requests |
The REST API does not replace the WordPress dashboard for every situation. Instead, it provides another way for applications to communicate with WordPress.
Best Practices for Using the WordPress REST API
Keep these recommendations in mind:
- Use HTTPS for API communication.
- Authenticate requests that modify data.
- Protect application passwords.
- Use unique namespaces for custom APIs.
- Version custom API endpoints.
- Add permission callbacks to protected routes.
- Validate incoming parameters.
- Sanitize data where appropriate.
- Escape output according to its context.
- Use pagination for large datasets.
- Avoid unnecessary API requests.
- Cache data when appropriate.
- Return only the information an application needs.
- Test custom endpoints before deploying them.
- Monitor server resources when API traffic is high.
Frequently Asked Questions
Is the WordPress REST API enabled by default?
Modern WordPress installations generally expose the standard REST API functionality by default, although individual endpoints, authentication requirements, plugins, security configurations, or server settings can affect access.
What URL is used for the WordPress REST API?
The standard API base is:
/wp-json/For example:
https://example.com/wp-json/Can I create WordPress posts using the REST API?
Yes. An authenticated request with sufficient permissions can create posts through the appropriate REST API endpoint.
Can I use the REST API with JavaScript?
Yes. JavaScript applications commonly use fetch() or other HTTP clients to retrieve WordPress data.
Can I build a mobile application with the WordPress REST API?
Yes. A mobile application can communicate with WordPress through REST API endpoints, provided authentication, permissions, and API requirements are handled correctly.
Can custom post types use the REST API?
Yes. Custom post types can be exposed through the REST API by configuring them appropriately, including show_in_rest => true.
Is the WordPress REST API secure?
The REST API itself provides mechanisms for authentication and authorization, but security depends heavily on how endpoints, credentials, permissions, input validation, and custom code are implemented.
Final Thoughts
The WordPress REST API turns WordPress into a flexible content platform that can communicate with external applications through HTTP and JSON.
For simple projects, you can start by retrieving posts from:
/wp-json/wp/v2/postsAs your requirements become more advanced, you can use authentication to create and modify content, integrate WordPress with JavaScript applications, expose custom post types, and build your own REST API endpoints.
When developing custom API functionality, security should always be a priority. Use HTTPS, protect credentials, validate input, implement permission checks, and return only the data that an application actually needs.
With these practices, the WordPress REST API can become a powerful foundation for integrations, headless websites, mobile applications, automation tools, and custom WordPress solutions.
This article can also be expanded into a more advanced follow-up covering how to create custom WordPress REST API endpoints with GET, POST, authentication, validation, and database queries.