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 Add a Custom REST API Endpoint

How to Add a Custom REST API Endpoint

Short answer

To add a custom REST API endpoint in WordPress, write a small plugin that calls register_rest_route on the rest_api_init hook with a unique vendor/v1 namespace, a route, a method, a callback, and a permission_callback. The callback takes the request and returns data, a WP_REST_Response object, or a WP_Error object, and WordPress turns the return value into JSON at the wp-json URL.

Key takeaways

  • A route is a URL, and an endpoint is one method plus a callback on that route.
  • Register routes with register_rest_route on the rest_api_init hook.
  • Namespaces should follow the vendor/v1 pattern, moving to v2 for breaking changes.
  • Every endpoint needs a permission_callback; public read-only routes use __return_true.
  • Callbacks should return data, a WP_REST_Response, or a WP_Error, never print JSON themselves.

What is a custom REST API endpoint?

A custom REST API endpoint is a URL on your site that runs your PHP code and returns JSON data to any app that calls it.

The WordPress REST API gives applications a way to read and write site data over HTTP. Learn WordPress states that the REST API provides an interface for applications to interact with a WordPress site, and that the Block Editor itself uses it to work with WordPress data (checked November 2026).

A route is the URL, and an endpoint is one method plus a callback on that route. Developer.WordPress.org states that a route refers to the URL, while an endpoint refers to the function behind it that matches a method and a URL (checked November 2026).

Learn WordPress states that a route can be mapped to different HTTP methods, and that the mapping of one method to a route is known as an endpoint (checked November 2026).

When should you add a custom endpoint?

Add one when an app, a script, or a front end needs data or an action that the built-in routes do not offer.

Common cases include a read-only feed of custom data, a search that joins two post types, or a small action such as recording a vote. If the built-in posts, pages, or search routes already return what you need, use them instead.

Do not add an endpoint to work around a missing plugin feature when a maintained plugin already solves it. A custom endpoint is code you must keep secure and updated.

Do not expose private data through a public endpoint. Anything the endpoint returns can be read by anyone who finds the URL, unless a permission check blocks it.

A guide on how to fix a REST API error in Site Health helps when the built-in API itself reports a fault before you add custom routes.

What do you need before you start?

You need a small plugin to hold the code, a local site for testing, and a plan for the namespace, the route, and who may call it.

Put the code in a plugin so it survives a theme change. A simple plugin file with a header comment is all you need, as the guide on creating a simple WordPress plugin explains.

Pick a namespace in the form vendor/v1, where vendor is your plugin or theme slug. Developer.WordPress.org states that namespaces should follow the pattern vendor/v1, and that you can move to v2 when you need to break compatibility (checked November 2026).

Decide the methods before you write the callback. A GET endpoint reads data, while POST, PUT, PATCH, and DELETE change data and need stricter permission checks.

Check the PHP version your site runs before you write the callback. A guide on whether WordPress supports PHP 8.4 covers the versions you can use.

How do you register a route?

Call register_rest_route on the rest_api_init hook, passing the namespace, the route, and an options array.

The handbook example registers a route with the namespace myplugin/v1 and the route /author, using the GET method and a callback function. 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).

add_action( 'rest_api_init', 'myplugin_register_routes' );
function myplugin_register_routes() {
    register_rest_route( 'myplugin/v1', '/hello',
        array(
            'methods'  => 'GET',
            'callback' => 'myplugin_hello',
        )
    );
}

Do not call register_rest_route before the rest_api_init hook. Developer.WordPress.org states that the function must not be used before the rest_api_init hook, and that routes must be namespaced with a plugin or theme name and version (checked November 2026).

Each route can hold more than one endpoint. Developer.WordPress.org states that each route can have any number of endpoints, with a method, a callback, and a permissions callback for each one (checked November 2026).

MethodWP_REST_Server constantUse it for
GETREADABLEReading data
POSTCREATABLECreating data
POST, PUT, PATCHEDITABLEUpdating data
DELETEDELETABLEDeleting data

The full URL for the example route is example.com/wp-json/myplugin/v1/hello. Developer.WordPress.org states that on sites without pretty permalinks, the same route is reached with the rest_route query value instead (checked November 2026).

How do you write the callback?

Write a function that takes the request, does the work, and returns data for WordPress to turn into JSON.

The callback receives a WP_REST_Request object as its first value. Developer.WordPress.org states that route arguments are merged into one set of values and added to the Request object, which is passed as the first value to the endpoint (checked November 2026).

Read values from the request with array access, such as the id value in the example below. Developer.WordPress.org states that you can read values through direct array access on the request object, or through its get_param helper (checked November 2026).

function myplugin_hello( $request ) {
    return array( 'message' => 'Hello from my first endpoint' );
}

Keep the callback short and let it return data only. Developer.WordPress.org states that a callback should always return data and should not send the response body itself, so the REST API server can handle headers, linking, and embedding (checked November 2026).

How do you set who can call the endpoint?

Add a permission_callback that returns true only for users who may use the endpoint, and never leave it out.

The permission callback runs before the main callback. Developer.WordPress.org states that the callback should return a boolean or a WP_Error value, and that a false value stops the request before the main callback runs (checked November 2026).

Check what the user can do, not just whether they are logged in. Developer.WordPress.org states that you should use current_user_can where possible, instead of checking only whether the user is logged in (checked November 2026).

register_rest_route( 'myplugin/v1', '/hello',
    array(
        'methods'             => 'GET',
        'callback'            => 'myplugin_hello',
        'permission_callback' => 'myplugin_can_read',
    )
);
function myplugin_can_read() {
    return current_user_can( 'edit_others_posts' );
}

Since WordPress 5.5, a missing permission callback raises a _doing_it_wrong notice. Developer.WordPress.org states that as of WordPress 5.5, the REST API issues that notice when no permission_callback is given (checked November 2026).

For a public read-only endpoint, use __return_true as the permission callback. Developer.WordPress.org states that for routes meant to be public, __return_true is the right permission callback (checked November 2026).

How do you validate and clean the input?

Declare each argument in the args array with a default, a required flag, and validation and cleaning callbacks.

Arguments are set in the args key for each endpoint. Developer.WordPress.org states that each argument can carry a default value, a required flag, a sanitize_callback, and a validate_callback (checked November 2026).

A validate callback returns true when the value is valid and false when it is not. Developer.WordPress.org states that a required argument with no value passed returns an error, unless a default value is set (checked November 2026).

Use sanitize_callback to change the input into a safe form, and validate_callback to reject bad input with an error. Developer.WordPress.org states that cleaning is useful when you would rather change the input than throw an error, such as with invalid HTML (checked November 2026).

Values arrive in a set order. Developer.WordPress.org states that the basic merge order for request values is body, query, URL, then defaults (checked November 2026).

How do you return data and errors?

Return plain data, a WP_REST_Response object, or a WP_Error object, and let WordPress build the HTTP response.

Plain values such as strings, numbers, and arrays are turned into JSON by the API. Developer.WordPress.org states that after the callback runs, the return value is turned into JSON and sent to the client (checked November 2026).

For a custom status code or header, wrap the data in a WP_REST_Response object. Developer.WordPress.org states that the object wraps normal body data and lets you return a custom status code or custom headers (checked November 2026).

For an error, return a WP_Error object with a status code in its data. Developer.WordPress.org states that the error details are passed to the client, along with a 500 status code by default, and that you can set a code such as 400 for bad input (checked November 2026).

Never print JSON and stop the script inside a callback. Developer.WordPress.org states that as of WordPress 5.5, a _doing_it_wrong notice is issued when the wp_send_json family of functions is used during a REST API request (checked November 2026).

How do you call and check the endpoint?

Open the URL in a browser for a public GET route, or call it with a REST client using an application password for a protected route.

For a public GET endpoint, open https://example.com/wp-json/myplugin/v1/hello in a browser and check the JSON response. Learn WordPress states that opening the wp-json URI of a site returns a JSON response that shows the routes and endpoints available (checked November 2026).

For a protected endpoint, use an application password. Learn WordPress states that application passwords can be set per user and are used to authenticate REST API requests (checked November 2026).

Application passwords arrived in WordPress 5.6, in December 2020. Developer.WordPress.org states that each password is tied to one user account, is meant for API access, and cannot be used to log in through wp-login.php (checked November 2026).

Make WordPress Core states that an application password is 24 characters long and holds over 142 bits of entropy (checked November 2026). Developer.WordPress.org states that the password is sent with HTTP Basic Auth, as a Base64 value of the username and password, and that you should always use HTTPS (checked November 2026).

WordPress.org lists HTTPS support among the requirements for running WordPress, which is the same protection application passwords rely on (checked November 2026).

A guide on how to check PHP error logs helps when a callback fails and the endpoint returns a 500 error with no detail.

A guide on how to control the WordPress Heartbeat API covers the built-in API that polls the server from the dashboard, which is a separate system from custom REST routes.

What mistakes should you avoid?

Avoid a missing permission callback, a generic namespace, and a callback that prints its own output.

A missing permission callback leaves the route open to anyone. Since WordPress 5.5, the missing callback also raises a notice, so treat that notice as a fault to fix, not as noise.

A generic namespace can clash with another plugin route. Developer.WordPress.org states that namespaces act as a vendor prefix to stop clashes between custom routes, and that two plugins with the same route name need unique namespaces (checked November 2026).

Do not call die or wp_send_json inside a callback. Return the data and let the API send it, so status codes, headers, and links are handled in one place.

Do not trust input from the request without validation. Declare each argument, check it with a validate callback, and clean it with a sanitize callback before you use it in a query or a database write.

Frequently asked questions

What is the difference between a route and an endpoint?

A route is the URL, such as myplugin/v1/hello. An endpoint is one HTTP method plus a callback on that route, such as the GET endpoint for that URL. One route can hold several endpoints, such as a GET endpoint that lists items and a POST endpoint that creates one.

Can a custom endpoint be public with no login?

Yes. Use __return_true as the permission_callback for a read-only endpoint that returns public data. For anything private or any write action, check a capability with current_user_can and return false for users who lack it.

How do I authenticate a call to a protected endpoint?

Create one from Users, then Profile, under the Application Passwords section. The password is shown once, so copy it at once. Send it with HTTP Basic Auth over HTTPS, using your username and the application password, never your main password.

Why does my endpoint return a 404 error?

Check that the plugin is active, that the code runs on rest_api_init, and that the namespace and route match the URL you called. Open the wp-json index in a browser to see whether your namespace is listed. A 404 often means a wrong URL or a missing registration.

Do I need a plugin to use the REST API?

No. The REST API is built into WordPress core, and register_rest_route is part of it. You only need a plugin or a theme file to hold your registration code, and no extra plugin is needed to add a route.

Does every endpoint need a permission callback?

Yes, if the endpoint returns data that should stay private, or if it writes, updates, or deletes anything. Public read-only endpoints can use __return_true. Any endpoint that changes data must check a capability first.

Sources

  1. Adding Custom Endpoints WordPress Developer Resources
  2. Routes and Endpoints WordPress Developer Resources
  3. register_rest_route() function reference WordPress Developer Resources
  4. The WordPress REST API Learn WordPress
  5. Application Passwords WordPress Developer Resources
  6. Application Passwords Make WordPress Core
  7. Requirements WordPress.org

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

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test