How to Upload an Image Using the WordPress REST API

Uploading images through the WordPress REST API is easier than it sounds once you know what's required. The REST API lets you create, update, or delete content remotely — and that includes uploading media files to your site's library. Here's how to do it cleanly with authentication and a simple upload request.

Step 1: Set Up Authentication

Before you can send an image to WordPress, the REST API needs to confirm who you are. There are a few ways to authenticate, but for quick testing you can use Basic Authentication. For production, use Application Passwords — they're built into WordPress and much safer.

To create a Basic Auth header, combine your username and password with a colon, like this: `username:password`. Then Base64-encode that string and prepend it with `Basic `. For example:

Basic YWRtaW46cGFzc3dvcmQ=

That string will go in the Authorization header when you make your request.

Step 2: Upload the Image with cURL

Now we'll send a POST request to WordPress's media endpoint. This example uses cURL, but you can do the same thing in Postman, JavaScript, Python, or any HTTP client. Replace the site URL, authorization string, and file path with your own:

curl --request POST https://your-site.com/wp-json/wp/v2/media \
--header "Authorization: Basic YWRtaW46cGFzc3dvcmQ=" \
--header "Content-Disposition: attachment; filename=example.jpg" \
--header "Content-Type: image/jpeg" \
--data-binary "@/path/to/image.jpg"

Here's what's going on in that command:

• The request is sent to `/wp-json/wp/v2/media`, which handles uploads in WordPress.
• The `Authorization` header includes your Base64-encoded credentials.
• `Content-Disposition` sets the uploaded filename in WordPress.
• `Content-Type` tells WordPress what kind of file it is — in this case, an image.
• `--data-binary` uploads the actual image file from your computer.

Step 3: Check the Response

If everything worked, the REST API will return a JSON response with information about the uploaded image — including its ID, URL, and metadata. You can then use that ID to attach the image to a post or display it wherever you need.

Step 4: Try It with Application Passwords (Recommended)

If you'd rather not use Basic Auth, WordPress supports Application Passwords out of the box. Create one under your user profile in the dashboard, and use it instead of your regular password. It works the same way with the REST API but is much safer for real-world use.

Useful Links

WordPress REST API Media endpoint reference:

Application Passwords guide on the Make WordPress Core blog:

That's all you need to upload images programmatically with the REST API. Once you've got authentication set up, you can extend this to handle other media types, automate uploads from external tools, or build custom dashboards that manage media directly.