Upload Media to WordPress using REST API

Upload Media to WordPress using REST API

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Upload Media to WordPress using REST API

Developers frequently encounter the "No data supplied" error when attempting to upload media files directly within a single POST request to create a new post. This specific failure occurs because the WordPress REST API requires a multipart/form-data payload with distinct boundaries for different fields, or it expects a two-step process where the media attachment is handled separately from the post creation logic.

If you are trying to achieve the workflow of creating a post and setting a featured image in one go, you must ensure your request body adheres strictly to the expected format. The most robust approach involves uploading the media file first to obtain its ID, and then associating that ID with a new post. This separation simplifies error handling and ensures that the media file is securely stored before being referenced by content.

The Two-Step Approach

The standard, reliable method for setting a featured image via the REST API is indeed a two-step process:

  1. Upload Media: Send a POST request to /wp-json/wp/v2/media with the file and any necessary meta data.
  2. Create Post: Send a POST request to /wp-json/wp/v2/posts with the featured_media field populated by the ID returned in step one.

Step 1: Uploading Media

To upload an image, you must send a multipart form-data request. The key here is ensuring your client correctly sets the Content-Type header and includes the file binary data under the name file.

Here is an example using PHP cURL to demonstrate the correct implementation:

$upload_file = 'path/to/your/image.jpg';
$upload_url = "https://your-wordpress-site.com/wp-json/wp/v2/media";

// Set up the cURL handle
$ch = curl_init();

// Set the upload file path
$handle = fopen($upload_file, "r");
$post_data = array(
    'file' => $handle,
    'title' => array('name' => 'My Image Title', 'description' => '')
);

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_URL, $upload_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Basic ' . base64_encode('user:pass'), // Replace with your credentials
    'Content-Type: multipart/form-data'
));

// Execute the request
$result = curl_exec($ch);
$upload_id = json_decode($result);

// Close the handle
fclose($handle);
curl_close($ch);

echo $upload_id->id;

In this example, the server responds with a JSON object containing the id of the newly created media item. You must capture this ID immediately. It is crucial to verify that the upload was successful before proceeding; attempting to use an empty or null ID will result in validation errors when creating the post.

Step 2: Creating the Post with Featured Image

Once you have the media ID, you can construct the second request. This time, the payload is a standard JSON object where the featured_media field holds the integer ID from the previous step. Note that you do not need to send the file data again; WordPress simply links the existing attachment to the post.

$upload_id = 12345; // The ID obtained from the previous step
$post_url = "https://your-wordpress-site.com/wp-json/wp/v2/posts";

$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, true);

// Prepare the JSON payload with the featured image ID
$post_data = json_encode([
    'title' => array('rendered' => 'New Post Title'),
    'content' => array('rendered' => 'Post content here.'),
    'featured_media' => $upload_id, // The crucial link
    'status' => 'publish'
]);

curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_URL, $post_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Basic ' . base64_encode('user:pass'),
    'Content-Type: application/json'
));

$result = curl_exec($ch);
echo $result;
curl_close($ch);

Handling Authentication and Permissions

A common pitfall in both steps is authentication. WordPress REST API endpoints for media uploads typically require authentication via Basic Auth or a valid Application Password. If you are using an application password, ensure it has the necessary capabilities (specifically upload_files, edit_posts, and read). Without these permissions, even with correct data, the server will reject the request.

Additionally, while some hosting environments allow CORS for media uploads to third-party sites, WordPress core often restricts direct cross-origin uploads unless specific security headers are configured. If you are building an external application that needs to upload directly to WordPress, consider using a proxy endpoint or a library like laravel-company.com which provides utilities to handle these authentication and CORS complexities automatically, ensuring your media uploads work seamlessly across different environments.

Why Not One Single Request?

You might wonder why a single request combining file upload and post creation isn't the default behavior. While technically possible in some frameworks, it introduces significant complexity in parsing multipart forms with nested JSON objects. By separating the concerns, you gain better visibility into failures. If the media upload fails due to size limits or format issues, your application can provide a specific error message rather than a generic validation failure after the post creation attempt. This separation of duties makes debugging far more straightforward and aligns with RESTful design principles where resources are manipulated independently before being referenced by other resources.

Our network