Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Upload a file using the WordPress REST API

Upload files

Using the REST API to upload a file to WordPress is quite simple. All you need is to send the file in a POST-Request to the wp/v2/media route.

There are two ways of sending a file. The first method simply sends the file in the body of the request. The following PHP script shows the basic principle:


$file = file_get_contents( 'test.jpg' );
$url = '';
$ch = curl_init();
$username = 'admin';
$password = 'password';

curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_POST, 1 );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $file );
curl_setopt( $ch, CURLOPT_HTTPHEADER, [
	'Content-Disposition: form-data; filename="example.jpg"',
	'Authorization: Basic ' . base64_encode( $username . ':' . $password ),
] );
$result = curl_exec( $ch );
curl_close( $ch );
print_r( json_decode( $result ) );

This would send the file test.jpg using CURL and create a new attachment.

You need to make sure, you are logged in as a user, who can upload media files. In our example, we are using Basic authentication. Via the headers you also have to send the Content-Disposition where you also add the filename.

The file itself is simply send in the body of the request.

The disadvantage of this way is, you can upload the file, but you can not alter the title or the caption in the same process. You would need to wait for the response and you would need to update the created media object in a second request.

Upload a file using Javascript

Have a look into this small plugin, to see one possibility, how to upload a file using Javascript:


 * Plugin Name: Upload a file via the REST API
 * Description: Upload a file with Javascript using the Rest API.
 * License: GPLv2

add_action( 'wp_enqueue_scripts', function() {

	wp_register_script( 'rest-uploader', plugins_url( '/assets/js/script.js', __FILE__ ), [ 'jquery' ] );
	$js_vars = [
		'endpoint' => esc_url_raw( rest_url( '/wp/v2/media/' ) ),
		'nonce'    => wp_create_nonce( 'wp_rest' ),
	wp_localize_script( 'rest-uploader', 'RestVars', $js_vars );
} );

add_shortcode( 'uploader', function() {
	wp_enqueue_script( 'rest-uploader' );

	<h2><?php esc_html_e( 'Upload a file', 'rest-uploader' ); ?></h2>
	<form method="post">
			<label for="uploader-title">
				<?php esc_html_e( 'Title', 'rest-uploader' ); ?>:
			<input id="uploader-title">

			<label for="uploader-caption">
				<?php esc_html_e( 'Caption', 'rest-uploader' ); ?>:
			<input id="uploader-caption">

			<label for="uploader-file">
				<?php esc_html_e( 'File', 'rest-uploader' ); ?>:
			<input id="uploader-file" type="file">
		<button id="uploader-send"><?php esc_html_e( 'Send', 'rest-uploader' ); ?></button>
	$content = ob_get_contents();
	return $content;
} );

In this plugin, we simply add a shortcode, which renders a basic form and hooks the following Javascript in:


jQuery( document ).ready( function() {
	jQuery( '#uploader-send' ).click( function( event ) {


		var title = jQuery( '#uploader-title' ).val();
		if ( ! title.length ) {
			alert( 'Please enter a title!' );
		var caption = jQuery( '#uploader-caption' ).val();
		if ( ! caption.length ) {
			alert( 'Please enter a caption!' );
		// Check, if a file is selected.
		if ( 'undefined' === typeof( jQuery( '#uploader-file' )[0].files[0] ) ) {
			alert( 'Select a file!' );
		// Grab the file from the input.
		var file = jQuery( '#uploader-file' )[0].files[0];
		var formData = new FormData();
		formData.append( 'file', file );
		formData.append( 'title', title );
		formData.append( 'caption', caption );

		// Fire the request.
		jQuery.ajax( {
			url: RestVars.endpoint,
			method: 'POST',
			processData: false,
			contentType: false,
			beforeSend: function ( xhr ) {
				xhr.setRequestHeader( 'X-WP-Nonce', RestVars.nonce );
			data: formData
		} ).success( function ( response ) {
			console.log( )
		} ).error( function( response ) {
			console.log( 'error' );
			console.log( response );
	} );

Basically, we are using Javascripts FormData-class to generate our form data and send this data to our rest endpoint. As we are not using the while requests body to send the file, in this example, we can upload a file and create the attachment in one request.


This comment has been minimized.

Copy link

@mizner mizner commented Oct 25, 2017

FormData is the key here, thanks for this @ahmadawais. Super helpful!


This comment has been minimized.

Copy link

@jongood01 jongood01 commented Oct 27, 2017

This doesn't work - the attachment get's created but the file is not stored in the uploads. Seems that endpoint is only for creating the attachment see on of the answers on:


This comment has been minimized.

Copy link

@JohnsonPhan JohnsonPhan commented Aug 3, 2018

Thank you @ahmadawais! The part script.js is so great!


This comment has been minimized.

Copy link

@ZalgirisKaunas ZalgirisKaunas commented Jan 24, 2019

this works great, but how could I use formData for multiple files?


This comment has been minimized.

Copy link

@smakman smakman commented Aug 28, 2019

I had to add the following line to be able to assign the response to $result:

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


This comment has been minimized.

Copy link

@rodvan rodvan commented Dec 17, 2019

{"code":"jwt_auth_bad_auth_header","message":"Authorization header malformed.","data":{"status":403}}


This comment has been minimized.

Copy link

@atashinbar atashinbar commented Jun 16, 2020

{"code":"jwt_auth_bad_auth_header","message":"Authorization header malformed.","data":{"status":403}}

Did you send token as a header parameter for authentication?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.