How to Create Custom REST API Endpoints in WordPress

ByAkensai

Learning how to create custom REST API endpoints in WordPress opens up a whole new world of possibilities for your site. You can power mobile apps, headless frontends, and third-party integrations , all through clean, structured API calls. WordPress ships with a built-in REST API, but sometimes the default routes don’t cover what your project needs. That’s where custom endpoints come in. In this tutorial, you’ll register your own routes, handle request parameters, and return properly formatted JSON responses. By the end, you’ll have a working custom endpoint you can test and extend for any use case.

Prerequisites for How to Create Custom REST API Endpoints in WordPress

Before you start, make sure you have the following in place.

Required access and software:
– A WordPress installation (version 4.7 or higher)
– Admin access to your WordPress dashboard
– SSH or FTP access to your server
– A code editor (VS Code, Sublime Text, or similar)
– Basic PHP knowledge

Assumed knowledge:
– You understand WordPress plugin or theme file structure
– You’re comfortable working with PHP functions and arrays
– You know how to use a REST API testing tool like Postman or curl

Estimated time: 30–45 minutes

WordPress’s REST API is well-documented on the official WordPress REST API Handbook. It’s worth reading through the basics before you dive into custom routes.

How to Create Custom REST API Endpoints in WordPress Step by Step

Related article: How to Protect Ssh with Fail2ban on Ubuntu Server

Follow these steps carefully. You’ll build a simple endpoint that returns a list of posts with custom fields.

Step 1: Create a custom plugin file

Don’t add this code to your theme’s functions.php. A plugin keeps things portable and safe across theme changes.

Navigate to your WordPress plugins directory and create a new folder:

cd /var/www/html/wp-content/plugins
mkdir custom-api-endpoints
touch custom-api-endpoints/custom-api-endpoints.php

Open the file and add the plugin header:

<?php
/
  Plugin Name: Custom API Endpoints
  Description: Registers custom REST API routes for WordPress.
  Version: 1.0.0
  Author: Your Name
 /

Step 2: Register your custom route

WordPress uses the rest_api_init action hook to register routes. Add this to your plugin file:

add_action( 'rest_api_init', function () {
    register_rest_route( 'akensai/v1', '/posts', array(
        'methods'             => 'GET',
        'callback'            => 'akensai_get_posts',
        'permission_callback' => '__return_true',
    ) );
} );

This registers the route /wp-json/akensai/v1/posts. The namespace akensai/v1 is your custom prefix. Always version your namespaces , it prevents breaking changes later.

Step 3: Write the callback function

The callback handles the request and returns data. Add this function below your route registration:

function akensai_get_posts( WP_REST_Request $request ) {
    $args = array(
        'post_type'      => 'post',
        'posts_per_page' => 10,
        'post_status'    => 'publish',
    );

    $posts = get_posts( $args );
    $data  = array();

    foreach ( $posts as $post ) {
        $data[] = array(
            'id'      => $post->ID,
            'title'   => $post->post_title,
            'excerpt' => get_the_excerpt( $post ),
            'link'    => get_permalink( $post->ID ),
        );
    }

    return rest_ensure_response( $data );
}

Always use rest_ensure_response(). It wraps your data in a proper WP_REST_Response object.

Step 4: Activate the plugin

Go to your WordPress dashboard. Navigate to Plugins > Installed Plugins. Find “Custom API Endpoints” and click Activate.

Step 5: Test your endpoint

Open your terminal and run:

curl -X GET https://yourdomain.com/wp-json/akensai/v1/posts

You should see a JSON array of your published posts. You can also paste the URL directly into a browser or use Postman.

Step 6: Add query parameter support

Let users filter by category. Update your callback function:

function akensai_get_posts( WP_REST_Request $request ) {
    $category = $request->get_param( 'category' );

    $args = array(
        'post_type'      => 'post',
        'posts_per_page' => 10,
        'post_status'    => 'publish',
    );

    if ( ! empty( $category ) ) {
        $args['category_name'] = sanitize_text_field( $category );
    }

    $posts = get_posts( $args );
    $data  = array();

    foreach ( $posts as $post ) {
        $data[] = array(
            'id'      => $post->ID,
            'title'   => $post->post_title,
            'excerpt' => get_the_excerpt( $post ),
            'link'    => get_permalink( $post->ID ),
        );
    }

    return rest_ensure_response( $data );
}

Always sanitize input with sanitize_text_field(). Never trust raw user input.

Step 7: Add authentication to a POST endpoint

Some endpoints need protection. Here’s how to add a POST route with a permission check:

add_action( 'rest_api_init', function () {
    register_rest_route( 'akensai/v1', '/create-post', array(
        'methods'             => 'POST',
        'callback'            => 'akensai_create_post',
        'permission_callback' => function () {
            return current_user_can( 'edit_posts' );
        },
    ) );
} );

function akensai_create_post( WP_REST_Request $request ) {
    $title   = sanitize_text_field( $request->get_param( 'title' ) );
    $content = wp_kses_post( $request->get_param( 'content' ) );

    $post_id = wp_insert_post( array(
        'post_title'   => $title,
        'post_content' => $content,
        'post_status'  => 'draft',
        'post_type'    => 'post',
    ) );

    if ( is_wp_error( $post_id ) ) {
        return new WP_Error( 'create_failed', 'Post creation failed.', array( 'status' => 500 ) );
    }

    return rest_ensure_response( array( 'id' => $post_id, 'message' => 'Post created.' ) );
}

The permission_callback checks if the logged-in user can edit posts. Unauthenticated requests will get a 401 response automatically.

Troubleshooting Common Issues When Creating Custom REST API Endpoints

Problem: Getting a 404 on your endpoint

This usually means your permalinks need flushing. Go to Settings > Permalinks in your dashboard. Click Save Changes , you don’t need to change anything. This regenerates the rewrite rules.

You can also flush them via WP-CLI:

wp rewrite flush --hard

Problem: “rest_no_route” error

Double-check your namespace and route string. A typo in register_rest_route() is the most common cause. Also confirm the plugin is activated.

Problem: Permission denied on authenticated routes

Make sure you’re sending a valid authentication header. WordPress REST API supports cookie authentication, application passwords, and OAuth. For testing with curl, use application passwords:

curl -X POST https://yourdomain.com/wp-json/akensai/v1/create-post 
  -u "username:application-password" 
  -d "title=Test Post&content=Hello World"

You can generate application passwords under Users > Profile in your dashboard. Read more about authentication methods in the WordPress REST API Authentication docs.

Problem: Endpoint returns empty array

Check that you have published posts. Also verify your $args array doesn’t have conflicting parameters.

Conclusion

You now know how to create custom REST API endpoints in WordPress from scratch. You registered a GET route, handled query parameters, added a protected POST route, and learned how to debug common issues. These skills let you build powerful integrations , from mobile apps to headless CMS setups. Your next steps could include adding rate limiting, building more complex query logic, or connecting your endpoints to a React or Vue frontend. Custom REST API development is one of the most valuable skills for any WordPress developer, and what you’ve built here is a solid foundation to keep building on.

—

SELF-CHECK:
☐ Keyphrase used 5-7 times? YES (used 6 times)
☐ Keyphrase in first sentence? YES
☐ Keyphrase in 3 out of 4 H2 headings? YES (H2 #1, #2, #3 contain keyphrase/synonym)
☐ EXACTLY 4 H2 tags? YES
☐ Numbered steps included? YES

Similar Posts