Upload1.3

Uploading Concepts


All MediaFire Upload APIs conform to the Multipart MIME standard. As such, the file name is specified in the filename field of the Content-Disposition header. An example for such a header can be found below:

Request
POST http://www.mediafire.com/api/unversioned/upload/simple.php?uploadkey=5bb66g94blnnk&session_token=aa22f5a968f827daf69fd6b3515110c43e036bc5d2ed8b81657dd1bdfe4b4c3e3ea6757d1f47bc3d6a001a16bc6f25abb486c5e779328a5769bd9ed6064edb69 HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:12.0) Gecko/20100101 Firefox/12.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip, deflate
X-Filehash:564dc5e9541a494e966066da8b2392e2e70e2438e4fcf4b0058cd9249abc4e1d
X-Filesize:29278
X-Filetype:text/plain
Content-Type: multipart/form-data; boundary=---------------------------41184676334
Content-Length: 29278

-----------------------------41184676334


Summer vacation
-----------------------------41184676334
Content-Disposition: form-data; name="image1"; filename="GrandCanyon.jpg"
Content-Type: image/jpeg

(Binary data not shown)
-----------------------------41184676334--
                        


In the example above, the custom headers X-Filesize and X-Filehash are supplied. While these headers are not required for all upload scenarios, their inclusion is strongly recommended as it will ensure a higher level of upload data integrity. Although it is not shown in this example, the custom header X-Filename is also supported. This will override the filename specified in the Content-Disposition header when Content-Type is application/octet-stream.


Upload Guide


General Information


MediaFire's API is designed to accommodate a number of upload scenarios. Each scenario is composed of two parts: the upload type and the file size. This design aides the developer in making intelligent decisions on which API method is best suited for the upload scenario they are confronted with.

MediaFire supports three upload methods: instant, single-chunk, and multi-chunk. Please note the instant upload method is not synonymous with the API method of the same name.

MediaFire does not recommend the use of any deprecated upload APIs.

Instant

  • 'Instant' simply means that the file you want to upload already exists in our system. Instead of wasting bandwidth and time uploading the full file we simply make a copy of the file already in the cloud.
  • This upload method is preferred when it is available.
  • A call to upload/check is necessary to determine if a file can be uploaded via this method.
  • It is not possible to perform an instant upload if the file already in our system has a legacy MD5 hash.

Single-Chunk

  • 'Single-chunk' refers to the method of uploading a file all at once in a single 'session'. Upload/simple, upload/update, upload/patch, and upload/add_web_upload all upload files in this manner. Upload/resumable uploads files in this manner when the file is 4MB or less.
  • A single-chunk upload cannot be resumed if the upload is interrupted. It must start over from the beginning.

Multi-Chunk

  • 'Multi-chunk' refers to the method of slicing a file into chunks(units) and uploading each chunk(unit) separately. This method is used by upload/resumable in order to upload files over 4MB.
  • A multi-chunk upload can be resumed if the upload is interrupted.
  • This upload method is preferred for medium to large files.

Helpful Tips

  • The following APIs must be POST requests as they require the binary contents of a file to be provided: upload/simple, upload/patch, upload/update, and upload/resumable.
  • All other upload API methods can be either GET or POST.
  • The POST body should only contain the binary file data.
  • Any other parameters passed to the API method, that are not headers, should be included in the URL Query String such as with a GET request.
  • All parameters that begin with 'x-' are headers and should be attached to the request in the standard way.

Upload Scenarios & Recommended APIs (in order of most recommended)
Upload Type Small Files (<= 4MB) Medium Files (> 4MB, <= 20MB) Large Files (> 20MB)
Normal upload/instant, upload/simple upload/instant, upload/resumable, upload/simple upload/instant, upload/resumable, upload/simple
Patch upload/instant, upload/patch upload/instant, upload/resumable, upload/patch upload/instant, upload/resumable, upload/patch
Update upload/instant, upload/update, upload/simple upload/instant, upload/resumable, upload/update, upload/simple upload/instant, upload/resumable, upload/update, upload/simple
Web upload/add_web_upload upload/add_web_upload upload/add_web_upload

Anatomy of an Upload


All MediaFire Upload APIs conform to the Multipart MIME standard. As such, the file name is specified in the filename field of the Content-Disposition header. An example for such a header can be found below:

Request
POST http://www.mediafire.com/api/unversioned/upload/simple.php?uploadkey=5bb66g94blnnk&session_token=aa22f5a968f827daf69fd6b3515110c43e036bc5d2ed8b81657dd1bdfe4b4c3e3ea6757d1f47bc3d6a001a16bc6f25abb486c5e779328a5769bd9ed6064edb69 HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:12.0) Gecko/20100101 Firefox/12.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip, deflate
x-filehash:564dc5e9541a494e966066da8b2392e2e70e2438e4fcf4b0058cd9249abc4e1d
x-filesize:29278
x-filetype:text/plain
Content-Type: multipart/form-data; boundary=---------------------------41184676334
Content-Length: 29278

-----------------------------41184676334


Summer vacation
-----------------------------41184676334
Content-Disposition: form-data; name="image1"; filename="GrandCanyon.jpg"
Content-Type: image/jpeg

(Binary data not shown)
-----------------------------41184676334--
                        


In the example above, the custom header x-filehash is supplied. While this header is not required for all upload scenarios, its inclusion is strongly recommended as it will ensure a higher level of upload data integrity. Although it is not shown in this example, the custom headers x-filename and x-filesize are also supported. The x-filesize header is required when Content-Type is multipart/form-data or application/octet-stream. The x-filename header is required when Content-Type is application/octet-stream(this is because the filename is not included in the POST body like it is for multipart/form-data).



File Size Information


MediaFire handles uploads slightly differently depending on the file size. This ensures data integrity as much as possible. Using the recommended API method for a given file size will ensure the best user experience.

<= 4MB
This is the lowest division that MediaFire recognizes for file size. Files up to 4MB should have no problem uploading as a single chunk. As such, there is no benefit in calling the upload/resumable API method in this scenario.

> 4MB, <= 20MB
Files between 4MB and 20MB are considered medium size files and, in many user scenarios, shouldn't have a problem uploading as a single chunk. The API upload/resumable is a more complicated method to implement. Therefore, the developer should use their own discretion as to whether upload/resumable is worth implementing.

> 20MB Files greater than 20MB are considered large size files and MediaFire highly recommends that developers utilize upload/resumable for these files as the risk for upload interruption is much greater.

Bitmap Information


APIs upload/resumable and upload/check (for a resumable upload in progress) responses contain a resumable_upload property. A sub-property of resumable_upload is bitmap. The bitmap property holds important information about the state of the resumable upload, specifically, which chunks have successfully uploaded to the cloud.

The client can use the bitmap information to find out which chunks are uploaded and which chunks still need to be uploaded by decoding the bitmap. The client will also need to know how many chunks are in the upload by looking at the number_of_units sub-property of resumable_upload.

The bitmap property contains two sub-properties: count and words. The property count indicates the number of words in the words property. The property words contains a set of integers, each of which represent a 16-bit word.

Each bit of a word represents a specific file chunk. A bit designated as 'on' represents a successfully uploaded file chunk.

The first word in the set represents file chunks 0 to 15. The second word represents file chunks 16 to 31, and so on.

Example: (count=2, words=[1258, 495] and number_of_units=28)

  • Convert word one to binary > 0000010011101010.
  • Read the result from right to left.
  • According to word one, chunks 1, 3, 5, 6, 7 and 10 have uploaded successfully.
  • Convert word two to binary > 0000000111101111.
  • Read the result from right to left.
  • According to word two, chunks 16, 17, 18, 19, 21, 22, 23 and 24 have uploaded successfully.
  • File chunks 0, 2, 4, 8, 9, 20, 25, 26, 27 and 28 have not uploaded successfully.

Below is a JavaScript function that can be used to decode the bitmap which is returned by upload/check or upload/resumable:

Response
/**
 * Decodes the bitmap returned by the upload/pre_upload api call (response.resumable_upload.bitmap)
 * Returns an array of units, the index being the unit's ID and the value being a boolean indicating whether the unit is uploaded or not
 */
function decodeBitmap(bitmap) {
  var uploadUnits = [];
  for (var i = 0; i < bitmap.count; i++) {
    var word = parseInt(bitmap.words[i], 10);
    var bin = word.toString(2);
    while(bin.length < 16) {
      bin = '0' + bin;
    }
    for (var b = 0; b < bin.length; b++) {
      uploadUnits[i*16 + b] = (bin[15 - b] == '1');
    }
  }
  return uploadUnits;
}
 
// Let's assume the API returned a JSON response which contains a bitmap under (response.resumable_upload.bitmap) and has two words with values 17 and 32.
bitmap = {count: 2, words: [17, 32]};
 
var unitUploaded = decodeBitmap(bitmap);
 
alert(unitUploaded[0]); // true
alert(unitUploaded[3]); // false
alert(unitUploaded[4]); // true
alert(unitUploaded[21]); // true
alert(unitUploaded[22]); // false

Normal Uploads


Normal uploads are simple file uploads that have no special cases associated with them. Most of the uploads you will be doing will be of this type.

Via upload/instant

Calling upload/check will determine if the file can be uploaded via this method.

Call upload/check to see if the file already exists in the cloud
  • Provide parameters filename, hash, and size.
  • If the response includes hash_exists=yes then the file can be uploaded 'instantly'. Otherwise, a full file upload is necessary via upload/simple or upload/resumable.

Call upload/instant
  • Provide parameters session_token, hash, size and filename.
A successful call to upload/instant will return a quickkey response property containing the new quickkey of the file.

Via upload/simple

It is not necessary to first call upload/check. However, upload/check can provide useful information such as whether the file already exists in the proposed destination by name, hash, or both.

Call upload/simple
  • Provide the binary file data via the POST body.
  • Provide header Content-Type.
  • Provide parameters session_token or filedrop_key.
A successful call's response will contain a sub-property called 'key' of doupload. This key is passed to upload/poll_upload to obtain the uploaded file's quickkey. Call upload/poll_upload on a cadence until a quickkey response property is returned.

Via upload/resumable

Files up to 4MB should have no problem uploading as a single chunk. As such, there is no benefit in calling the upload/resumable API method in this scenario. You must first call upload/check before calling upload/resumable to determine if the file can be uploaded via this method.

Call upload/check
  • Provide parameters session_token, filename, hash, size, and resumable=yes.
If the response contains a resumable_upload property then the file can be uploaded via this method. You will need the information contained in the resumable_upload response property for the resumable upload. The file should be sliced into chunks based on the unit_size property of resumable_upload. Once sliced, you should have a total chunk count equal to the number_of_chunks property of resumable_upload.

Call upload/resumable
  • Provide the binary file data of the chunk being uploaded via the POST body.
  • Provide headers x-filesize, x-filehash, x-unit-hash, x-unit-id, and x-unit-size.
You will call upload/resumable once for each chunk that needs uploading. Each successful call to upload/resumable will return a doupload and resumable_upload property. The value of the 'key' sub-property of doupload will be passed to upload/poll_upload once the 'all_units_ready' sub-property of resumable_upload equals 'yes'. The key value will always be the same for every uploaded chunk of the same file.

If upload/resumable has been called for all chunks but all_units_ready equals 'no,' a processing error occurred with one or more of the chunks during or after the upload. Analyze the bitmap sub-property of resumable_upload to find out which chunk(s) failed and re-upload them.

Once all chunks are uploaded and all_units_ready of resumable_upload equals 'yes', call upload/poll_upload on a cadence until a quickkey response property is returned.

Patch Uploads


Patch uploads are uploads of patch(diff) files created via the algorithm used by xdelta 3 and VCDIFF/RDC3284. The system uses the patch file to update the contents of a file already existing in the user's account.

This method is useful when client software retains a local copy of the user's file. If the user updates the file locally, the client sync process needs to only upload the patch file to update the cloud copy of the file. This method saves time and bandwidth over a full file upload.

Terms
  • Source File: The user's file which will be patched using the patch file.
  • Patched File: The source file after the patch file has been applied.
  • Patch File: The file used to patch the source file to create the patched file.

Via upload/instant

Calling upload/check will determine if the file can be uploaded via this method.

Call upload/check to see if the patched file already exists in the cloud
  • Provide parameters filename(of the source file), hash(of the patched file), and size(of the patched file).
If the response includes hash_exists=yes then the file can be uploaded 'instantly'. Otherwise, a patch upload will be necessary via upload/patch or upload/resumable.

Call upload/instant
  • Provide parameters session_token, quick_key(of the source file), hash(of the patched file), and size(of the patched file).
A successful call to upload/instant will return a result response property equal to 'Success'.

Via upload/patch

It is not necessary to first call upload/check before calling upload/patch.

Call upload/patch
  • Provide the binary file data of the patch file being uploaded via the POST body.
  • Provide header Content-Type.
  • Provide parameters quick_key(of the source file), source_hash(of the source file), target_hash(the patched file's hash), and target_size(the patched file's size).
A successful call's response will contain a sub-property called 'key' of doupload. This key is passed to upload/poll_upload to obtain the result of the upload. Call upload/poll_upload on a cadence until a result response property is returned equal to '0'.

Via upload/resumable

Files up to 4MB should have no problem uploading as a single chunk. As such, there is no benefit in calling the upload/resumable API method in this scenario. It is necessary to first call upload/check before calling upload/resumable to determine if the file can be uploaded via this method.

Call upload/check
  • Provide parameters filename, hash, and size of the patch file to be uploaded as well as resumable=yes.
If the response contains a resumable_upload property then the patch file can be uploaded via this method. You will need the information contained in the resumable_upload response property for the resumable upload.

The patch file should be sliced into chunks based on the unit_size property of resumable_upload. Once sliced, you should have a total chunk count equal to the number_of_chunks property of resumable_upload.

Call upload/resumable

  • Provide the binary file data of the chunk being uploaded via the POST body.
  • Provide headers x-filesize, x-filehash, x-unit-hash, x-unit-id, and x-unit-size.
  • Provide parameters quick_key(of the source file), source_hash(of the source file), target_hash(the patched file's hash), and target_size(the patched file's size).
You will call upload/resumable once for each chunk that needs uploading. Each successful call to upload/resumable will return a doupload and resumable_upload property. The value of the 'key' sub-property of doupload will be passed to upload/poll_upload once the 'all_units_ready' sub-property of resumable_upload equals 'yes'. The key value will always be the same for every uploaded chunk of the same file.

If upload/resumable has been called for all chunks but all_units_ready equals 'no,' a processing error occurred with one or more of the chunks during or after the upload. Analyze the bitmap sub-property of resumable_upload to find out which chunk(s) failed and re-upload them.

Once all chunks are uploaded and all_units_ready of resumable_upload equals 'yes', call upload/poll_upload on a cadence until a result response property is returned equal to '0'.

Update Uploads


Update uploads are similar to patch uploads, but differ in that they do not patch a source file using a patch file. Update uploads entirely replace the contents of the source file with the contents of the uploaded file.

This method is the same as copying a file located on your computer to a folder that already has a file in it with the same name. Your operating system will ask if you want to replace the file in the folder with the one being copied. Only the file name is retained from the source file.

Terms
  • Source File: The user's file which will be updated using the update file.
  • Updated File: The source file after the contents have been replaced with the contents of the update file.
  • Update File: The file used to update the source file to create the updated file.

Via upload/instant

Calling upload/check will determine if the file can be uploaded via this method.

Call upload/check to see if the updated file already exists in the cloud
  • Provide parameters filename(of the source file), hash(of the update file), and size(of the update file).
If the response includes hash_exists=yes then the file can be uploaded 'instantly'. Otherwise, an update upload is necessary via upload/update, upload/simple, or upload/resumable .

Call upload/instant
  • Provide parameters session_token, quick_key(of the source file), hash(of the update file), and size(of the update file).
A successful call to upload/instant will return a result response property equal to 'Success'.

Alternatively, if you do not know the quick_key of the source file you can set the action_on_duplicate property to 'replace'. This method will only work if the destination folder has a file already in it with the same name as the update file.

Via upload/update

It is not necessary to first call upload/check before calling upload/update.

Call upload/update
  • Provide the binary file data of the update file being uploaded via the POST body.
  • Provide parameters session_token and quick_key(of the source file).
A successful call to upload/update will return a doupload response property with a sub-property 'key'. Call upload/poll_upload on a cadence until a result response property is returned equal to '0'.

Via upload/simple

It is not necessary to first call upload/check before calling upload/simple. Updating a file via this method only works if the destination folder has a file already in it with the same name as the update file. This can be checked with a call to upload/check.

Call upload/simple
  • Provide the binary file data of the update file being uploaded via the POST body
  • Provide header Content-Type.
  • Provide parameters session_token or filedrop_key and action_on_duplicate=replace.
A successful call's response will contain a sub-property called 'key' of doupload. This key is passed to upload/poll_upload to obtain the uploaded file's quickkey. Call upload/poll_upload on a cadence until a result response property is returned equal to '0'.

Via upload/resumable

Files up to 4MB should have no problem uploading as a single chunk. As such, there is no benefit in calling the upload/resumable API method in this scenario. It is necessary to first call upload/check before calling upload/resumable to determine if the file can be uploaded via this method.

Call upload/check
  • Provide parameters filename, hash, and size of the update file to be uploaded as well as resumable=yes.
If the response contains a resumable_upload property then the update file can be uploaded via this method. You will need the information contained in the resumable_upload response property for the resumable upload.

The update file should be sliced into chunks based on the unit_size property of resumable_upload. Once sliced, you should have a total chunk count equal to the number_of_chunks property of resumable_upload.

Call upload/resumable
  • Provide the binary file data of the chunk being uploaded via the POST body.
  • Provide headers x-filesize, x-filehash, x-unit-hash, x-unit-id, and x-unit-size.
  • Provide parameters quick_key(of the source file), source_hash(of the source file), target_hash(the updated file's hash), and target_size(the updated file's size).
You will call upload/resumable once for each chunk that needs uploading. Each successful call to upload/resumable will return a doupload and resumable_upload property. The value of the 'key' sub-property of doupload will be passed to upload/poll_upload once the all_units_ready sub-property of resumable_upload equals 'yes'. The key value will always be the same for every uploaded chunk of the same file.

If upload/resumable has been called for all chunks but all_units_ready equals 'no,' a processing error occurred with one or more of the chunks during or after the upload. Analyze the bitmap sub-property of resumable_upload to find out which chunk(s) failed and re-upload them.

Once all chunks are uploaded and all_units_ready of resumable_upload equals 'yes', call upload/poll_upload on a cadence until a result response property is returned equal to '0'.

Alternatively, if you do not know the quick_key of the source file you can set the action_on_duplicate property to 'replace'. This method will only work if the destination folder has a file already in it with the same name as the update file. This can be checked with a call to upload/check.

Web Uploads


Web uploads allow a user to copy a file residing at a specified URL to their account.

Via upload/add_web_upload


Call upload/add_web_upload
  • Provide parameters session_token, url, and filename.
A successful call to upload/add_web_upload will return an upload_key response property. This key is passed to upload/get_web_uploads to obtain the results of the upload. Call upload/get_web_uploads and pass upload_key and all_web_uploads=yes to obtain all of the newly uploaded file's information.


Upload Scenarios


Uploading a Small File
Any size file can be uploaded either as a single unit or as a "resumable" upload, likely split into chunks. Resumable uploading is highly recommended for larger files, especially when connectivity problems are expected (as with mobile devices). However, since the smallest possible chunk size is 4 MB, resumable uploads offer no real benefit for files under that size. Follow the instructions in this section to upload a file as a single unbroken unit, a "simple" upload.

  • Pass filename to upload/check to look for naming conflicts. A destination path will also need to be specified via folder_key or filedrop_key for the base, as well as an optional relative path including any subfolders that may need to be created.
  • If storage_limit_exceeded is returned as "yes", then the upload cannot be completed because the user lacks sufficient storage space.
  • If file_exists is returned as "yes", then there is a naming conflict that must be settled, probably by passing a user-specified value of action_on_duplicate to upload/simple.
  • Call upload/simple. An upload key should be returned under doupload.
  • Pass the upload key to upload/poll_upload every few seconds until it returns the quickkey of your newly uploaded file.

Uploading a Large File

The basic premise of a resumable upload is that a large file is broken up into several uniform chunks. Each of these units is essentially treated as a separate file for the purpose of uploading. When all of the units have been uploaded successfully, they are reassembled on the server side. If the upload is interrupted at some point, only the chunk(s) in the process of uploading at that moment will need to be restarted.

  • Pass filename to upload/check to look for naming conflicts. A destination path will also need to be specified via folder_key or filedrop_key for the base, as well as an optional relative path including any subfolders that may need to be created.
  • If storage_limit_exceeded is returned as "yes", then the upload cannot be completed because the user lacks sufficient storage space.
  • If file_exists is returned as "yes", then there is a naming conflict that must be settled, probably by passing a user-specified value of action_on_duplicate to upload/resumable.
  • Use the data returned under resumable_upload to split your file up into number_of_units chunks of unit_size bytes each.
  • For each chunk, call upload/resumable with appropriate header data. An upload key should be returned under doupload.
  • Pass the file's SHA-256 hash and size in bytes with resumable="yes" to ensure that all_units_ready is returned as "yes".
  • If all_units_ready is returned as "no", analyze bitmap to determine which units failed to upload. Repeat the last two steps until all_units_ready is returned as "yes".
  • Pass the upload key to upload/poll_upload every few seconds until it returns the quickkey of your newly uploaded file.


Resuming an Upload

If a resumable upload is not completed within three days, it will expire. If connectivity is lost during an upload, it can be resumed anytime within that three-day window by following these steps::
  • Pass the filename and path information to upload/check with resumable="yes". all_units_ready should be returned as "no".
  • If necessary, use the data returned under resumable_upload to split your file up into number_of_units chunks of unit_size bytes each.
  • Analyze bitmap to determine which units still need to be uploaded. This field is an array of 16-bit values. each value represents 16 chunks. Each bit indicates whether a unit is uploaded or not. For example, a value of 19, which is 10011 in binary, indicates that units 0, 1, and 4 are uploaded.
  • For each chunk, call upload/resumable with appropriate header data. An upload key should be returned under doupload.
  • Pass the file's SHA-256 hash and size in bytes to upload/check with resumable="yes" to ensure that all_units_ready is returned as "yes".
  • If all_units_ready is returned as "no", analyze bitmap to determine which units failed to upload. Repeat the last two steps until all_units_ready is returned as "yes".
  • Pass the upload key to upload/poll_upload every few seconds until it returns the quickkey of your newly uploaded file.


Decoding the Bitmap

Below is a JavaScript function that can be used to decode the bitmap returned by upload/check API :
/**
* Decodes the bitmap returned by the upload/pre_upload api call (response.resumable_upload.bitmap) * Returns an array of units, the index being the unit's id and the value being a boolean indicating * whether the unit is uploaded or not */ function decodeBitmap(bitmap) {     var uploadUnits = [];     for (var i = 0; i < bitmap.count; i++) {         var word = parseInt(bitmap.words[i], 10);         var bin = word.toString(2);         while(bin.length < 16) {             bin = '0' + bin;         }         for (var b = 0; b < bin.length; b++) {             uploadUnits[i*16 + b] = (bin[15 - b] == '1');         }     }<     return uploadUnits; } // Let's assume the API returned a JSON response which contains a bitmap under (response.resumable_upload.bitmap) having 2 words with values 17 and 32. bitmap = {count: 2, words: [17, 32]}; var unitUploaded = decodeBitmap(bitmap); alert(unitUploaded[0]); // true alert(unitUploaded[3]); // false alert(unitUploaded[4]); // true alert(unitUploaded[21]); // true alert(unitUploaded[22]); // false

"Instant" Uploads
Before choosing between performing a simple upload or a resumable upload, a third possibility should be explored, which is highly preferable, but not always possible. If a file has been uploaded before, by any user, then it already exists in the cloud and there is no need to repeat the upload in full. In order to check the file to be uploaded against all the files in the cloud, a hash of the file must be computed client-side and sent along with the exact file size. This may be a time-consuming process for very large files, but the benefit of performing an instant upload is also proportionally greater.

  • On the initial call to upload/check, include a SHA-256 hash of the file and its size in bytes.
  • If hash_exists is returned as "yes", then call upload/instant.

Legacy MD5 hash
After calling upload/poll_upload API, you will receive the file data information including the hash. Although MD5 hash is deprecated, you may still get MD5 hash for certain files that already exist in our system. For these files, it is not possible to perform future instant uploads at this time. The reason for this discrepancy is the upload/instant API only accepts SHA256 hashes.

Updating an Existing File
If your upload is meant to overwrite a file that already exists in the cloud, you'll be referencing the file by quickkey instead of name and location. The technique varies depending on whether simple or resumable uploading is used.
For simple uploads:
  • Pass the file's SHA-256 hash and size in bytes to upload/check.
  • If hash_exists is returned as "yes", then pass the file's hash and size to upload/instant.
  • Otherwise, pass the file's quickkey to upload/update. An upload key should be returned under doupload.
  • Pass the upload key to upload/poll_upload every few seconds until it returns a result of '0' (success).

For resumable uploads:
  • Pass the file's SHA-256 hash and size in bytes to upload/check with resumable="yes".
  • If hash_exists is returned as "yes", then pass the file's hash and size to upload/instant.
  • Otherwise, use the data returned under resumable_upload to split your file up into number_of_units chunks of unit_size bytes each.
  • For each chunk, call upload/resumable with appropriate header data. An upload key should be returned under doupload.
  • Pass the file's SHA-256 hash and size in bytes to upload/check with resumable="yes" to ensure that all_units_ready is returned as "yes".
  • If all_units_ready is returned as "no", analyze bitmap to determine which units failed to upload. Repeat the last two steps until all_units_ready is returned as "yes".
  • Pass the upload key to upload/poll_upload every few seconds until it returns a result of '0' (success).

Applying a Patch to a File
If you have a delta file "diff" patch to apply to a file in the cloud, you'll need to hash the original file before the patch, the patch itself, and the complete file after the patch.
  • Pass the file's quickkey to upload/patch, along with the original file's hash ('source_hash'), the patched file's hash ('target_hash'), and the patched file's size in bytes ('target_size'). An upload key should be returned under doupload.
  • Pass the upload key to upload/poll_upload every few seconds until it returns a result of '0' (success).

For resumable uploads:
  • Pass the complete file's SHA-256 hash and size in bytes to upload/check.
  • If hash_exists is returned as "yes", then pass the file's hash and sizeto upload/instant.
  • Otherwise, pass the patch file's SHA-256 hash and size in bytes to upload/check.
  • Use the data returned under resumable_upload to split your patch file up into number_of_units chunks of unit_size bytes each.
  • For each chunk, call upload/resumable with appropriate header data, along with the original file's hash ('source_hash'), the patched file's hash ('target_hash'), and the patched file's size in bytes ('target_size'). An upload key should be returned under doupload.
  • Pass the patch file's SHA-256 hash and size in bytes to upload/check with resumable="yes" to ensure that all_units_ready is returned as "yes".
  • If all_units_ready is returned as "no", analyze bitmap to determine which units failed to upload. Repeat the last two steps until all_units_ready is returned as "yes".
  • Pass the upload key to upload/poll_upload every few seconds until it returns a result of '0' (success).

Patch uploads allow the client to upload a delta file (patch) to update the content of an existing file instead of uploading the entire file. To update a file with a patch, four additional GET arguments need to be passed:
  • quick_key : The quickkey of the file being patched/updated.
  • source_hash : The hash of the file being patched/updated.
  • target_hash : A SHA-256 check-sum of the target file.
  • target_size : The size of the target file.

The patch file should be created on the client-side using the same algorithm used by xdelta 3. Please check http://xdelta.org/ for more details.


Add Web Upload


GET http://www.mediafire.com/api/1.3/upload/add_web_upload.php
POST http://www.mediafire.com/api/1.3/upload/add_web_upload.php

Description : Adds a new web upload and returns the Upload Key on success.

Required Parameters:

  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature) Alternatively, you may use an action token in place of a session token.
  • url : The URL of the file you wish to be placed into your MediaFire account.
  • filename : The UTF-8 encoded name, plus extension, of the file to be created(3 to 255 characters in length).

Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • folder_key : The key that identifies the destination folder. If not passed, then it will return the root folder (session token is then required). Alternatively, you may pass myfiles as a folderkey moniker for the root folder.
  • response_format : 'xml' or 'json' (default 'xml')

Response Properties

Name Description Type Value
upload_key An alpha-numeric ID key used with upload/get_web_upload to determine the status of the file upload string
error The numerical error code integer 129
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:


Example 1 (Success with JSON):

Request
HTTPS://www.mediafire.com/api/upload/add_web_upload.php?session_token=&url=http://static.befunky.com/V4/images/BeFunkyLogo_onBlack_v1.png&filename=funky.png&response_format=json&signature=
Response
{
   action: upload/add_web_upload,
   upload_key: aogvo25zua,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}

Example 1 (Failure with XML - Error 129):

Request
HTTPS://www.mediafire.com/api/upload/add_web_upload.php?session_token=&url=http://static.befunky.com/V4/images/BeFunkyLogo_onBlack_v1.png&filename=funky.png&response_format=json&signature=
Response
<action>upload/add_web_upload</action>
<message>One or more parameters for this request are invalid</message>
<error>129</error>
<result>Error</result>
<current_api_version>1.3</current_api_version>

Check


GET http://www.mediafire.com/api/1.3/upload/check.php
POST http://www.mediafire.com/api/1.3/upload/check.php

Description: Checks if a duplicate filename exists in the destination folder and verifies folder permissions for non-owner uploads. When a hash is supplied, hash_exists is returned to indicate whether an instant upload is possible. Several flags are returned, which can be "yes" or "no": file_exists (with the same name and location), different_hash (if file_exists), hash_exists (somewhere in the cloud), in_account (if hash_exists), and in_folder (if hash_exists). If a path is supplied, a folder_key will also be returned to be used for a subsequent upload. If resumable is supplied as "yes", a resumable upload will be initiated, and resumable_upload will be returned containing the relevant data.


Required Parameters:

  • filename : The UTF-8 encoded name, plus extension, of the file to be created(3 to 255 characters in length). Filename is not required if both hash and size are passed.

Relative Parameters:

  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature) Alternatively, you may use an action token in place of a session token.
  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.
  • size : File size in bytes. This needs to be passed if hash is passed. Required if resumable="yes".
  • hash : SHA-256 hash of the file. If not passed, no content checks can be made. Required if resumable="yes". Hash is not case sensitive.
  • filedrop_key : The destination filedrop folder key. Required if session_token is not passed. Ignored if session_token or folder_key is passed.

Optional Parameters:

  • folder_key : The destination folder to store the file. If it's not passed, then the file will be stored in the root folder. Alternatively, you may pass myfiles as a folderkey moniker for the root folder.
  • filedrop_key : This is the key of the file drop to upload to. This parameter is honored only if folder_key is not passed.
  • path : An absolute or relative path to upload the file to. Absolute paths begin with a slash; relative paths do not and are in relation to the specified folder_key or filedrop_key. Non-existent folders will not be created by this call.
  • resumable : Indicates whether this upload can be resumed. 'yes' or 'no' (default 'no').
  • response_format : 'xml' or 'json' (default 'xml')

Response Properties

Name Description Type Value
hash_exists The file already exists, by hash, somewhere in the cloud and can be instant uploaded. Returned only if hash was passed to the API. flag yes/no
in_account The file already exists, by hash, in the account. Returned only if hash_exists=yes. flag yes/no
in_folder The file already exists, by hash, in the folder. Returned only if hash_exists=yes. flag yes/no
file_exists The file already exists, by name, in the target destination. flag yes/no
different_hash Specifies if all the file units have been uploaded flag yes/no
resumable_upload -> number_of_units The total number of files to be uploaded string
resumable_upload -> unit_size The size, in bytes, of each file unit to be uploaded with the exception of the last unit, which is usually less than unit_size object
resumable_upload -> bitmap A collection of information relevant to the file unit bitmap object
resumable_upload -> bitmap -> count The number of words in the words object string
resumable_upload -> bitmap -> words A collection of 16bit integers used as a bitmask where each bit represents the upload status of a file unit object
resumable_upload -> upload_key An alpha-numeric ID key used with upload/poll_upload to determine the status of the file upload string
available_space The amount of available space in the user's account string
used_storage_size The amount of storage used string
storage_limit The storage limit for the user's account string
storage_limit_exceeded 'yes' or 'no' flag yes/no
all_units_ready Appears if a resumable upload is in progress under the subheading "resumable_upload". Indicates if the upload is ready for a resumable upload. 'yes' or 'no' flag yes/no
number_of_units Appears if a resumable upload is in progress under the subheading "resumable upload". Indicates the number of units that will upload. integer
unit_size Appears if a resumable upload is in progress under the subheading "resumable upload". Indicates the size of each unit that will upload. integer
count Appears if a resumable upload is in progress under subheading "bitmap". Indicates the number of words in the words property. integer
word Appears if a resumable upload is in progress under subheading "words" which is under subheading "bitmap". Contains a set of integers, each of which represent a 16-bit word. list of integers
upload_key Appears if a resumable upload is in progress. An alpha-numeric key used with upload/poll_upload to determine the status of the file upload. string
error The numerical error code integer 110, 114
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:


Example 1 (Success with XML - checking availability of performing an instant upload):

Request
HTTPS://www.mediafire.com/api/upload/check.php?session_token=&filename=error395.png&hash=&size=32392&response_format=xml&signature=
Response
<action>upload/check</action>
<hash_exists>yes</hash_exists>
<in_account>no</in_account>
<in_folder>no</in_folder>
<file_exists>no</file_exists>
<available_space>1084468221134</available_space>
<used_storage_size>11021106</used_storage_size>
<storage_limit>1084479242240</storage_limit>
<storage_limit_exceeded>no</storage_limit_exceeded>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>

Example 2 (Success with JSON - checking if file exists in destination):

Request
HTTPS://www.mediafire.com/api/upload/check.php?session_token=&filename=error395.png&hash=&size=32392&path=/Test002&response_format=json&signature=
Response
{
   action: upload/check,
   hash_exists: yes,
   in_account: no,
   in_folder: no,
   file_exists: yes,
   different_hash: yes,
   duplicate_quickkey: 30d1fzd0pe02jg0,
   available_space: 1084468221134,
   used_storage_size: 11021106,
   storage_limit: 1084479242240,
   storage_limit_exceeded: no,
   folder_key: k80i7ih0c40fr,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}

Example 3 (Success with XML - beginning a resumable upload):

Request
HTTPS://www.mediafire.com/api/upload/check.php?session_token=&filename=error395.png&hash=&size=32392&filedrop_key=&resumable=yes&response_format=xml&signature=
                        
Response
<action>upload/check</action>
<hash_exists>yes</hash_exists>
<in_account>yes</in_account>
<in_folder>yes</in_folder>
<file_exists>yes</file_exists>
<different_hash>no</different_hash>
<duplicate_quickkey>f12cb3uzj2dhkl7</duplicate_quickkey>
<resumable_upload>
   <all_units_ready>no</all_units_ready>
   <number_of_units>1</number_of_units>
   <unit_size>4194304</unit_size>
   <bitmap>
      <count>1</count>
      <words>
         <word>0</word>
      </words>
   </bitmap>
</resumable_upload>
<available_space>1084468188742</available_space>
<used_storage_size>11053498</used_storage_size>
<storage_limit>1084479242240</storage_limit>
<storage_limit_exceeded>no</storage_limit_exceeded>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>

Example 4 (Success with JSON - returning upload_key for an in-progress or recently finished resumable upload):

Request
HTTPS://www.mediafire.com/api/upload/check.php?session_token=&filename=t2.png&hash=&size=553&resumable=yes&response_format=json&signature=
Response
{
   action: upload/check,
   hash_exists: yes,
   in_account: yes,
   in_folder: yes,
   file_exists: yes,
   different_hash: no,
   duplicate_quickkey: 3f09rdrbhvwbmq3,
   resumable_upload:{
      all_units_ready: yes,
      number_of_units: 1,
      unit_size: 4194304,
      bitmap:{
         count: 1,
         words:[
            1,
         ]
      }
      upload_key: 6sctzwbr1xe,
   }
   available_space: 1084451685527,
   used_storage_size: 27556713,
   storage_limit: 1084479242240,
   storage_limit_exceeded: no,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}

Example 5 (Failure with XML - Error 114 checking permission to upload to a folder not owned by session user and lacking edit permissions):

Request
HTTPS://www.mediafire.com/api/upload/check.php?session_token=&filename=error395.png&hash=&size=32392&folder_key=ll19p52lfxqoe&resumable=no&response_format=xml&signature=
                        
Response
<action>upload/check</action>
<message>Access denied</message>
<error>114</error>
<result>Error</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>


Get Options


GET http://www.mediafire.com/api/1.3/upload/get_options.php
POST http://www.mediafire.com/api/1.3/upload/get_options.php

Description: Get upload preferences. Preferences include the following data: disable_flash, disable_html5, disable_instant, & action_on_duplicate.

Required Parameters:

  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature) Alternatively, you may use an action token in place of a session token.

Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • response_format : 'xml' or 'json' (default 'xml')

Response Properties

Name Description Type Value
disable_flash Indicates the availability of using the Adobe flash based client-side uploader. 'yes' or 'no'. flag yes/no
disable_html5 Indicates the availability of using the HTML5 based client-side uploader. 'yes' or 'no'. flag yes/no
disable_instant Indicates the availability of performing "instant" uploads. 'yes' or 'no'. flag yes/no
action_on_duplicate Specifies the default action to take when the file already exists, by name, in the destination folder. skip, keep, replace. string skip, keep, replace
used_storage_size The amount of storage space, in bytes, the session user's files are currently occupying. integer
storage_limit The total amount of storage space, in bytes, available to the session user. integer
storage_limit_exceeded Indicates if the session user's files are occupying more space than is available to the user. 'yes' or 'no'. flag yes/no
error The numerical error code integer
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:


Example 1 (Success with JSON):

Request
HTTPS://www.mediafire.com/api/upload/get_options.php?session_token=&response_format=json&signature=
Response
{
   action: upload/get_options,
   disable_flash: no,
   disable_html5: no,
   disable_instant: yes,
   action_on_duplicate: replace,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
} 

Get Web Uploads


GET http://www.mediafire.com/api/1.3/upload/get_web_uploads.php
POST http://www.mediafire.com/api/1.3/upload/get_web_uploads.php

Description: Returns a list of queued, in progress, and finished web uploads along with their associated information.

Required Parameters:

  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature) Alternatively, you may use an action token in place of a session token.

Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • all_web_uploads : Specifies whether to return all web uploads(queued, active and completed). Includes all available file information for the uploads. If no, only active uploads, status 2 through 4, will be returned. no(default) or yes.
  • upload_key : Filter results by an upload key obtained from upload/add_web_upload. If the specified upload is completed, it will only be returned if all_web_uploads=yes.
  • response_format : 'xml' or 'json' (default 'xml')


Response Properties

>
Name Description TypeValue
upload_key An alpha-numeric ID key used with upload/get_web_upload to determine the status of the file upload string
active Indicates if the web upload is active (status 2-4) flag yes/no
quickkey The ID of the file string
filename The file name of the web upload string
created The date and time the file was created string timestamp
status_code A numerical code indicating the upload's status integer 1, 2, 3, 4, 6, 99
status A description of the upload's status string waiting to start, webupload is starting, transfer is in progress, downloaded, verifying transfer, transfer complete
error_status The numerical ID for errors occuring during the upload string 9(downloader curl), 10(file too big), 11(file too small), 14(downloader), 15(HTTP), 16(missing file), 17(image too big), 19(virus), 38(partial file), 39(storage full)
url The url of the web upload string
eta The amount of time left for the web upload to complete uploading string
size The size of the web upload in bytes integer
percentage The amount, in percent, of the web upload which has uploaded integer
error The numerical error code integer
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:


Example 1 (Success with JSON - all_web_uploads=no):

Request
HTTPS://www.mediafire.com/api/upload/get_web_uploads.php?session_token=&response_format=json&signature=
                        
Response
{
   action: upload/get_web_uploads,
   web_uploads:[
      {
         uploadkey: 93do9m68rx,
         active: yes,
         quickkey: ,
         filename: 007.zip,
         created: 2015-02-16 17:30:40,
         status_code: 3,
         status: Transfer is in progress,
         error_status: 0,
         url: http://download.thinkbroadband.com/20MB.zip,
         eta: 4 seconds,
         size: 20971520,
         percentage: 84,
      }
   ]
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}
                        

Example 2 (Success with XML - all_web_uploads=yes):

Request
HTTPS://www.mediafire.com/api/upload/get_web_uploads.php?session_token=&all_web_uploads=yes&response_format=xml&signature=
Response:
<action>upload/get_web_uploads</action>
<web_uploads>
   <web_upload>
      <uploadkey>93do9m68rx</uploadkey>
      <active>no</active>
      <quickkey>qjffa4pk82zydy3</quickkey>
      <filename>007.zip</filename>
      <created>2015-02-16 17:30:40</created>
      <status_code>99</status_code>
      <status>Transfer complete</status>
      <error_status>0</error_status>
      <url>http://download.thinkbroadband.com/20MB.zip</url>
      <eta>Transfer completed</eta>
      <size>20971520</size>
      <percentage>100</percentage>
   </web_upload>
   <web_upload>
      <uploadkey>3gp4nwrt83</uploadkey>
      <active>no</active>
      <quickkey>52v2pmig8q0uv47</quickkey>
      <filename>006.jpg</filename>
      <created>2015-02-16 17:19:18</created>
      <status_code>99</status_code>
      <status>Transfer complete</status>
      <error_status>0</error_status>
      <url>http://upload.wikimedia.org/wikipedia/commons/6/66/Big_size_chess_6759_CRI_08_2009_Langosta_Beach.jpg</url>
      <eta>Transfer completed</eta>
      <size>1094574</size>
      <percentage>100</percentage>
   </web_upload>
   <web_upload>
      <uploadkey>o1ld6w6ga1</uploadkey>
      <active>no</active>
      <quickkey></quickkey>
      <filename>002.jpg</filename>
      <created>2015-02-16 17:13:21</created>
      <status_code>1</status_code>
      <status>Waiting to start</status>
      <error_status>0</error_status>
      <url>http://snackface.files.wordpress.com/2009/06/huge.jpg</url>
      <eta>n/a</eta>
      <size>0</size>
      <percentage>1</percentage>
   </web_upload>
</web_uploads>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>

Example 3 (Success with JSON - all_web_uploads=yes filtering by upload_key):

Request
HTTPS://www.mediafire.com/api/upload/get_web_uploads.php?session_token=&all_web_uploads=yes&upload_key=2xpae4meae&response_format=json&signature=
Response:
{
   action: upload/get_web_uploads,
   web_uploads:[
      {
         uploadkey: 2xpae4meae,
         active: yes,
         quickkey: ,
         filename: 008.zip,
         created: 2015-02-16 17:38:06,
         status_code: 2,
         status: Webupload is starting,
         error_status: 0,
         url: http://download.thinkbroadband.com/200MB.zip,
         eta: n/a,
         size: 0,
         percentage: 1,
      }
   ]
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}

Instant


POST http://www.mediafire.com/api/1.3/upload/instant.php

Notes: The response property device_revision was renamed to new_device_revision.

Description: If the file already exists in the cloud, by hash and size match, copy the file into the session user's account instead of re-uploading it. Returns a quickkey on successful instant upload.

Required Parameters:

  • size : File size in bytes. This needs to be passed if hash is passed. Required if resumable="yes".
  • hash : SHA-256 hash of the file. If not passed, no content checks can be made. Required if resumable="yes". Hash is not case sensitive.

Relative Parameters:

  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature) Alternatively, you may use an action token in place of a session token. Required only if filedrop_key or folder_key are not passed.
  • filename : The UTF-8 encoded name, plus extension, of the file to be created(3 to 255 characters in length). Required if quickkey is not passed.
  • filedrop_key : The destination filedrop folder key. Required if session_token is not passed. Ignored if session_token and folder_key is passed.
  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • quick_key : To update an existing file, pass its quickkey.
  • folder_key: The destination folder to store the file. If it's not passed, then the file will be stored in the root folder. Alternatively, you may pass myfiles as a folderkey moniker for the root folder.
  • path : An absolute or relative path to upload the file to. Absolute paths begin with a slash; relative paths do not and are in relation to the specified folder_key or filedrop_key. Non-existent folders will not be created by this call.
  • action_on_duplicate : When a file with the same name is encountered in the same folder, this determines how the conflict is resolved. Possible values are "skip" to ignore the upload (default), "keep" to keep both files with a new one with a number appended, and "replace" to overwrite the old file adding to its version history.
  • mtime : Date-time used as the creation time of the file. If not passed the current server time is used. Refer to the following document for valid date/time formats: http://www.php.net/manual/en/datetime.formats.php
  • version_control : Specify version control. This takes effect only on a file update. Can take the following values: "keep_revision" (default), to keep the version being updated, and "none", to overwrite the version being updated.
  • previous_hash : The hash of the last known version of the file before it was modified. Ignored if quickkey is not passed or action_on_duplicate is not replace. If previous_hash does not match device 0's(cloud) file's hash the file will be uploaded as a new file with a new quickkey and file name.
  • response_format : 'xml' or 'json' (default 'xml')


Response Properties

Name Description Type Value
quickkey The quickkey of the web upload string
filename The file name of the web upload string
newrevision Deprecated object
newfolderrevision Deprecated object
new_device_revision The revision number of the device
error The numerical error code integer
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:


Example 1 (Success with JSON):

Request
HTTPS://www.mediafire.com/api/1.3/upload/instant.php?session_token=&hash=&size=2986&filename=t1.png&version_control=none&response_format=json&signature=
                        
Response
{
   action: upload/instant,
   quickkey: adz62va71ryktm8,
   filename: t1.png,
   newrevision:{
      revision: 28.1,
      epoch: 1430324685,
   }
   newfolderrevision:{
      revision: 45,
      epoch: 1430348561,
   }
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
   new_device_revision: 161699,
}                        



Example 2 (Success with XML - updating preexisting file):

Request
HTTPS://www.mediafire.com/api/1.3/upload/instant.php?session_token=&hash=&size=553&filename=t2.png&quick_key=adz62va71ryktm8&version_control=none&previous_hash=&response_format=xml&signature=
                        
Response
<response>
  <action>upload/instant</action>
  <quickkey>32d392v90o3pvd3</quickkey>
  <filename>whatever.gif</filename>
  <newrevision>
    <revision>456222</revision>
  </newrevision>
  <newfolderrevision>
    <revision>123</revision>
  </newfolderrevision>
  <result>Success</result>
  <new_device_revision>22554</new_device_revision>
  <current_api_version>1.3</current_api_version>
</response>                        

Patch


POST http://www.mediafire.com/api/1.3/upload/patch.php

Note: This API currently returns a Content-Type=text/xml header even when the response is in JSON format.
Deprecated parameter previous_hash removed.

Description: Patch uploads are uploads of patch(diff) files created via the algorithm used by xdelta 3 and VCDIFF/RDC3284. The system uses the patch file to update the contents of a file already existing in the user's account. This method is useful when client software retains a local copy of the user's file. If the user updates the file locally, the client sync process needs to only upload the patch file to update the cloud copy of the file. This method saves time and bandwidth over a full file upload.

Required Parameters:

POST Body
The content(binary data) of the patch file to upload. The patch file should be created on the client-side using the same algorithm used by xdelta 3. Please check http://xdelta.org/ for more details.

URL Query Data
  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature) Alternatively, you may use an action token in place of a session token.
  • quick_key : The file key of a file already in the session user's account. This file will be updated utilizing the uploaded patch file.
  • source_hash : The hash of the file to be patched. Hash is not case sensitive.
  • target_hash : The expected hash of the target file. A SHA256 check-sum of the target file. Hash is not case sensitive.
  • target_size : The expected size of the target file.

Header Data
  • Content-Type : Either "application/octet-stream" or "multipart/form-data + boundary".

Relative Parameters:

URL Query Data
  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Header Data
  • x-filename : The name plus extension of the patch file being uploaded. The name should be 3 to 255 characters in length and UTF-8 encoded. Required and only used for Content-Type: "application/octet-stream".
  • x-filesize : The size, in bytes, of the patch file being uploaded. Required and only used for Content-Type: "application/octet-stream".

Optional Parameters:


URL Query Data
  • mtime : The date/time of the update. If not set, the current server time will be used. Refer to the following document for valid date/time formats: http://www.php.net/manual/en/datetime.formats.php
  • version_control : Specifies if file versions are made and, if so, what type. If quickkey is not passed or action_on_duplicate is not replace this parameter is ignored. create_patches creates the new version and maintains patches to the updated version, keep_revision creates the new version and maintains the updated version as a full file, none creates the new version and maintains no patches or full files of the updated version. create_patches(default), keep_revision, none.
  • response_format : xml(default) or json.


Response Properties

Name Description Type Value
result Numerical ID of checks done before any file data is actually transferred (this appears under the subheading 'doupload') integer 0(success), -10, -12, -26, -50, -54, -70, -80, -120-, 140, -200(internal server error), -14(destination does not exist), -31, -40(unknown upload error), -32(missing file data), -41(max file size exceeded), -42(max specified file size exceeded), -43(file partially uploaded), -44(no file uploaded), -45(missing a temporary folder), -46(failed to write file to disk), -47(a PHP extension stopped the upload), -48(invalid file size), -49(missing file name), -51(file size mismatch), -90(source hash mismatch), -203(invalid quickkey or file does not belong to session user), -204(session user lacks permission to patch file), -205(session user lacks permission to destination), -206(the destination has been deleted), -207(the uploaded file is not a valid patch file), -701, -881(max file size exceeded for free users), -700, -882(max file size exceeded)
key An alpha-numeric ID key used with upload/poll_upload to determine the status of the file upload (this appears under the subheading 'doupload') string
server The server type uploaded to string live
error The numerical error code integer
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.

Examples:


Example 1 (Success with JSON)

Request
HTTPS://www.mediafire.com/api/1.3/upload/patch.php?session_token=&quick_key=4znq80iev8p5n38&source_hash=&target_hash=&target_size=35&version_control=none&response_format=json&signature=
Response
{
   action: upload/patch,
   doupload:{
      result: 0,
      key: mp2inhei2x6,
   }
   server: live,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}
                        

Poll Upload


GET http://www.mediafire.com/api/1.3/upload/poll_upload.php
POST http://www.mediafire.com/api/1.3/upload/poll_upload.php

Description: Check for the status of a current Upload. This can be called after using any of the upload family of APIs which return an upload key. Use the key returned (response.doupload.key) to request the status of the current upload. Keep calling this API every few seconds until you get the status value 99 which means that the upload is complete. The quickkey of the file and other related information is also returned when the upload is complete.

Required Parameters:

  • key : The upload key obtained in the response from upload/patch, upload/resumable, upload/simple, upload/update.

Relative Parameters:

  • none

Optional Parameters:

  • response_format : 'xml' or 'json' (default 'xml')


Response Properties

Name Description Type Value
result This appears under the subheading "doupload". Numerical ID of checks done before any file data is actually transferred integer 0(success), -20(invalid upload key), -80(upload key not found)
status This appears under the subheading "doupload". The numerical ID for the status of the upload integer '0' = Unknown or no status available for this key, '2' = Key is ready for use, '3' : Upload is in progress, '4' = Upload is completed, '5' = Waiting for verification, '6' = Verifying File, '11' = Finished verification, '17' = Upload is in progress, '18' = Waiting for assembly, '19' = Assembling File, '99' = No more requests for this key, '0' - Unknown or no status available for this key
description This appears under subheading the "doupload". This is a descriptive status of the poll upload string unknown or no status available, key is ready for use, upload in progress, upload complete, awaiting verification, verifying, verification finished, awaiting assembly, assembling file, meta data mining, no more requests for this key
fileerror The numerical ID of an error with the file integer 1(max file size exceeded), 2(file size cannot be 0), 3(bad RAR file), 4(bad RAR file), 5(virus), 6(file lost), 7(hash or size mismatch), 8(unknown internal error), 9(bad RAR file), 10(unknown internal error), 12(failed database insert), 13(file name exists in destination, skipping), 14(destination does not exist), 15(storage full), 16(update revision conflict), 17(patch failed), 18(account blocked), 19(failed to create destination)
quickkey This appears under the subheading "doupload". The quickkey of the file. string
hash The SHA256 hash of the file. string
filename The name of the file. string
size This appears under the subheading "doupload". The size of the file. string
created The date and time the file was created. datetime string
revision This appears under the subheading "doupload". The revision of the file. string
resumable_upload A collection of information needed for resumable uploads. Returned when resumable=yes. object
resumable_upload -> all_units_ready Specifies if all the file units have been uploaded. string yes/no
resumable_upload -> number_of_units The total number of file units to be uploaded. integer
resumable_upload -> unit_size The size, in bytes, of each file unit to be uploaded with the exception of the last unit, which is usually less than unit_size. integer
resumable_upload -> bitmap A collection of information relevant to the file unit bitmap . object
resumable_upload -> bitmap -> words A collection of 16bit integers used as a bitmask where each bit represents the upload status of a file unit. object
resumable_upload -> bitmap -> count The number of words in the word object. integer
error The numerical error code integer
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string


Examples:


Example 1 (Success with JSON):

Request
HTTPS://www.mediafire.com/api/upload/poll_upload.php?key=aenu8aofwsc&response_format=json
Response
{
   action: upload/poll_upload,
   doupload:{
      result: 0,
      status: 99,
      description: No more requests for this key,
      fileerror: ,
      quickkey: c3v6smx0x5gxz5v,
      hash: 48f29c2d04f54ba0462541fd58ae8f712147c4a77b000b08297f8b562f406fc7,
      filename: first.txt,
      size: 79,
      created: 2015-02-17 14:43:48,
      revision: 159981,
      resumable_upload: ,
   }
   result: Success,
   current_api_version: 1.3,
}
                        

Example 2 (Success with a resumable upload - JSON):

Request
HTTPS://www.mediafire.com/api/upload/poll_upload.php?key=8t2ln2yh33m&response_format=json
Response
{
   action: upload/poll_upload,
   doupload:{
      result: 0,
      status: 17,
      description: Upload is in progress,
      fileerror: ,
      quickkey: ,
      hash: ,
      filename: ,
      size: ,
      created: ,
      revision: ,
      resumable_upload:{
         all_units_ready: no,
         number_of_units: 9,
         unit_size: 1048576,
         bitmap:{
            count: 1,
            words:[
               1,
            ]
         }
      }
   }
   result: Success,
   current_api_version: 1.3,
}
                        

Example 3 (Success with fileerror - XML):

Request
HTTPS://www.mediafire.com/api/upload/poll_upload.php?key=13rpjdx2x32&response_format=xml
Response
<action>upload/poll_upload</action>
<doupload>
   <result>0</result>
   <status>99</status>
   <description>No more requests for this key</description>
   <fileerror>7</fileerror>
   <quickkey></quickkey>
   <hash></hash>
   <filename></filename>
   <size></size>
   <created></created>
   <revision></revision>
   <resumable_upload></resumable_upload>
</doupload>
<result>Success</result>
<current_api_version>1.3</current_api_version>
                        

Example 4 (Success with result -80 XML):

Request
HTTPS://www.mediafire.com/api/upload/poll_upload.php?key=i36ln2yh78m&response_format=xml
Response
<action>upload/poll_upload</action>
<doupload>
   <result>-80</result>
   <status></status>
   <description></description>
   <fileerror></fileerror>
   <quickkey></quickkey>
   <hash></hash>
   <filename></filename>
   <size></size>
   <created></created>
   <revision></revision>
   <resumable_upload></resumable_upload>
</doupload>
<result>Success</result>
<current_api_version>1.3</current_api_version>
                        

Pre Upload (deprecated)


GET http://www.mediafire.com/api/1.3/upload/pre_upload.php
POST http://www.mediafire.com/api/1.3/upload/pre_upload.php

Deprecated. Use upload/check and upload/instant instead.

Description: Determines if instant upload is possible, if a duplicate filename exists in the destination folder, and also verifies folder permissions for non-owner uploads. This returns a 'quickkey' on successful instant upload. Otherwise, 'new_hash' and 'duplicate_name' are returned, which can be 'yes' or 'no'. Based on those values, the uploader performs a regular upload or resends the same pre_upload request with the desired action. If 'path' is specified and an instant upload was not possible, the 'folder_key' will also be returned to be used for a regular upload.View a flow chart of the upload process.

Note: This API returns text/xml content-type regardless of whether you request 'XML' or a 'JSON' response format. It is important to note that even though the content-type field is incorrect, the payload will conform to the requested type."

Required Parameters:

  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature).
  • filename : File name UTF-8 encoded. This is not required if quick_key and hash are passed.

Optional Parameters:

  • signature : This is the call signature that is required to authenticate a type 2 session token transaction.
  • hash : SHA256 hash of file, if not passed, only duplicate name is checked.
  • size : File size. This must passed if hash is passed.
  • mtime : The date/time of the update. If not set, the current server time will be used. Refer to the following document for valid date/time formats: http://www.php.net/manual/en/datetime.formats.php
  • upload_folder_key : The folderkey of the folder you wish to upload your file to. If not passed, the destination folder is the root folder.
  • quick_key : To update an existing file, pass the quickkey of that file. A file update requires hash to be passed too, otherwise quick_key is ignored.
  • filedrop_key : This is the key of the file drop to upload to. This parameter is honored only if upload_folder_key is not passed.
  • action_on_duplicate : This is used in the case where there are duplicate file names in the same upload folder. The values are 'keep' (default) (to keep both files with the same name, the new file will have a numeric digit added to it), 'skip' (this will ignore the upload), and 'replace' (this will override the original file with the new file).
  • resumable : In the circumstance of the upload being interrupted, this indicates whether this upload can be resumed. 'yes' or 'no' (default 'no').
  • path : An absolute or relative path to upload the file to. Absolute paths begin with a slash; relative paths do not and are in relation to the specified folder_key or filedrop_key. Non-existent folders will not be created by this call.
  • response_format : 'xml' or 'json' (default 'xml')

Errors:
  • 114 - Non-owner upload does not have write permissions to the folder.


Example 1:

Request
http://www.mediafire.com/api/1.3/upload/pre_upload.php?session_token=123456789012345678901234567890123456789012345678901234567890&filename=uploaded%5fby%5fhash%2ezip&hash=65dd21d705d5680cf7777286d627de9e799ef03e2ff0374df297382e3f1cd1d1&size=34221&upload_folder_key=f7a1ec50dcbbe&action_on_duplicate=replace
                        
Response
<response>
  <action>upload/pre_upload</action>
  <newrevision>
      <revision>12</revision>
      <epoch>1352305437</epoch>
  </newrevision>
  <newfolderrevision>
      <revision>79</revision>
      <epoch>1352305451</epoch>
  </newfolderrevision>
  <quickkey>276hrbqba55zz7h</quickkey>
  <device_revision>123</device_revision>
     <deprecated>yes</deprecated>
  <result>Success</result>
  <current_api_version>2.12</current_api_version>
</response>
                        

Example 2:

Request
http://www.mediafire.com/api/1.3/upload/pre_upload.php?session_token=123456789012345678901234567890123456789012345678901234567890&filename=my_document.doc&hash=68dd21d705d5680cf7777286d627de9e799ef03e2ff0374df297382e3f1cd1d1&size=34221&resumable=yes
                        
Response
<response>
  <action>upload/pre_upload</action>
  <new_hash>yes</new_hash>
  <duplicate_name>no</duplicate_name>
  <resumable_upload>
    lt;all_units_ready>no</all_units_ready>
    <number_of_units>28</number_of_units>
    <unit_size>2097152</unit_size>
    <bitmap>
        <count>2</count>
        <words>
            <word>1258</word>
            <word>495</word>
        </words>
    </bitmap>
  </resumable_upload>
  <deprecated>yes</deprecated>
  <result>Success</result>
  <current_api_version>2.12</current_api_version>
</response>
                        

Example 3 (In this example, we assume that the user has run out of storage space):

Request
http://www.mediafire.com/api/1.3/upload/pre_upload.php?session_token=123456789012345678901234567890123456789012345678901234567890&filename=uploaded%5fby%5fhash%2ezip&hash=65dd21d705d5680cf7777286d627de9e799ef03e2ff0374df297382e3f1cd1d1&size=34221
                        
Response
<response>
  <action>upload/pre_upload</action>
  <duplicate_name>no</duplicate_name>
  <used_storage_size>54882441579</used_storage_size>
  <storage_limit>53687091200</storage_limit>
  <storage_limit_exceeded>yes</storage_limit_exceeded>
  <deprecated>yes</deprecated>
  <result>Success</result>
  <current_api_version>2.12</current_api_version>
</response>
                        

Resumable


POST http://www.mediafire.com/api/1.3/upload/resumable.php

Note: This API currently returns a Content-Type=text/xml header even when the response is in JSON format.

Description: Uploading large files through upload/simple can take a long time. Additionally, if it fails, re-uploading the file starts from the beginning. With a resumable upload you can upload the file in small units or chunks. Therefore, if one unit fails to upload, only that unit is re-uploaded. upload/resumable can only be called after a call to upload/check which will then initiate the resumable upload. This API returns the upload key when successful. After you upload all the units, you can pass the key to upload/poll_upload to get the quickkey. Please refer to the documentation about the API upload/poll_upload for more details.

Required Parameters:


POST Body
  • The content(binary data) of the file to upload.
(see Upload Guide for more details)

Header Data
  • x-filesize : The size, in bytes, of the binary file data.
  • x-filehash : A SHA256 hash of the file. Hash is not case sensitive.
  • x-unit-hash : A SHA256 hash of the unit being uploaded. Hash is not case sensitive.
  • x-unit-id : An ID of the unit. Can be 0 through Number of units - 1
  • x-unit-size : The size of the unit being uploaded.
  • Content-Type : Either "application/octet-stream" or "multipart/form-data + boundary".

Relative Parameters:


URL Query Data
    session_token : A session access token to authenticate the user's current session. Required if filedrop_key or folder_key is not passed. Alternatively, a valid action token may be used instead.
  • filedrop_key : A key representing a filedrop folder. Required if session_token is not passed. Ignored if folder_key is passed.
  • source_hash : The hash of the target file to be patched. Required if quickkey is passed. Hash is not case sensitive.
  • target_hash : The expected hash of the target file after it is patched. A SHA256 check-sum of the target file. Required if quickkey is passed. Hash is not case sensitive.
  • target_size : The expected size of the target file after is is patched. Required if quickkey is passed. Hash is not case sensitive.
  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Header Data
  • x-filename : The name plus extension of the patch file being uploaded. The name should be 3 to 255 characters in length and UTF-8 encoded. Required and only used for Content-Type: "application/octet-stream".

Optional Parameters:


URL Query Data
  • quick_key : The file key of a file already in the session user's account. This file will be updated with the content of the uploaded file.
  • folder_key : The destination folder key. If not passed the API will use the cloud root folder. Alternatively, you may pass myfiles as a folderkey moniker for the root folder.
  • path : An absolute or relative path to upload the file to. Absolute paths begin with a slash; relative paths do not and are in relation to the specified folder_key or filedrop_key. Non-existent folders will be created by this call.
  • action_on_duplicate : Specifies the action to take when the file already exists, by name, in the destination folder. skip ignores the upload, keep uploads the file and makes the file name unique by appending a number to it, and replace overwrites the old file, possibly adding to its version history. skip (default), keep, replace.
  • mtime : Date-time used as the creation time of the file. If not passed the current server time is used. Click here for valid date/time formats.
  • version_control : Specifies if file versions are made and, if so, what type. If quickkey is not passed or action_on_duplicate is not replace this parameter is ignored. create_patches creates the new version and maintains patches to the updated version, keep_revision creates the new version and maintains the updated version as a full file, none creates the new version and maintains no patches or full files of the updated version. create_patches(default), keep_revision, none.
  • previous_hash : The hash of the last known version of the file before it was modified. If quickkey is not passed or action_on_duplicate is not replace this parameter is ignored. If previous_hash does not match the cloud file's hash the file will be uploaded as a new file with a new quickkey and file name. Hash is not case sensitive.
  • response_format : xml(default) or json.

Response Properties

Name Description Type Value
result Numerical ID of checks done before any file data is actually transferred (this appears under the subheading 'doupload') integer 0(success), -10, -12, -26, -50, -54, -70, -80, -120-, 140, -200(internal server error), -14(destination does not exist), -31, -40(unknown upload error), -32(missing file data), -41(max file size exceeded), -42(max specified file size exceeded), -43(file partially uploaded), -44(no file uploaded), -45(missing a temporary folder), -46(failed to write file to disk), -47(a PHP extension stopped the upload), -48(invalid file size), -49(missing file name), -51(file size mismatch), -90(source hash mismatch), -203(invalid quickkey or file does not belong to session user), -204(session user lacks permission to patch file), -205(session user lacks permission to destination), -206(the destination has been deleted), -207(the uploaded file is not a valid patch file), -701, -881(max file size exceeded for free users), -700, -882(max file size exceeded)
key An alpha-numeric ID key used with upload/poll_upload to determine the status of the file upload (this appears under the subheading 'doupload') string
server The server type uploaded to string live
resumable_upload A collection of information needed for resumable uploads. Returned when resumable=yes. object
resumable_upload -> all_units_ready Specifies if all the file units have been uploaded. string yes/no
resumable_upload -> number_of_units The total number of file units to be uploaded. integer
resumable_upload -> unit_size The size, in bytes, of each file unit to be uploaded with the exception of the last unit, which is usually less than unit_size. integer
resumable_upload -> bitmap A collection of information relevant to the file unit bitmap . object
resumable_upload -> bitmap -> words A collection of 16bit integers used as a bitmask where each bit represents the upload status of a file unit. object
resumable_upload -> bitmap -> count The number of words in the word object. integer
device_revision The revision of the device integer
error The numerical error code integer
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.



Examples:


Example 1 (Success with XML - unit 1 of a new file upload):

Request
HTTPS://www.mediafire.com/api/upload/resumable.php?session_token=&version_control=none&response_format=xml&signature=
                        
Response
<action>upload/resumable</action>
<doupload>
   <result>0</result>
   <key>8t2ln2yh33m</key>
</doupload>
<server>live</server>
<resumable_upload>
   <all_units_ready>no</all_units_ready>
   <number_of_units>9</number_of_units>
   <unit_size>1048576</unit_size>
   <bitmap>
      <count>1</count>
      <words>
         <word>1</word>
      </words>
   </bitmap>
</resumable_upload>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>
                        

Example 2 (Success with JSON - patch of existing file):

Request
HTTPS://www.mediafire.com/api/upload/resumable.php?session_token=&source_hash=&target_hash=&target_size=79&quick_key=v6zhd7ocuo92sl7&version_control=none&response_format=json&signature=
                        
Response
{
   action: upload/resumable,
   doupload:{
      result: 0,
      key: a29d0al9lie,
   }
   server: live,
   resumable_upload:{
      all_units_ready: yes,
      number_of_units: 1,
      unit_size: 4194304,
      bitmap:{
         count: 1,
         words:[
            1,
         ]
      }
   }
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}
                        

Example 3 (Success with XML - update of existing file):

Request
HTTPS://www.mediafire.com/api/upload/resumable.php?session_token=&quick_key=ridrad9hrx86219&version_control=keep_revision&previous_hash=&response_format=json&signature=
                        
Response
<action>upload/resumable</action>
<doupload>
   <result>0</result>
   <key>zf07g05vbgs</key>
</doupload>
<server>live</server>
<resumable_upload>
   <all_units_ready>yes</all_units_ready>
   <number_of_units>1</number_of_units>
   <unit_size>4194304</unit_size>
   <bitmap>
      <count>1</count>
      <words>
         <word>1</word>
      </words>
   </bitmap>
</resumable_upload>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>
                        

Set Options


GET http://www.mediafire.com/api/1.3/upload/set_options.php
POST http://www.mediafire.com/api/1.3/upload/set_options.php

Description: This API will set the user's preferences for uploads when using the JavaScript Upload client on the MediaFire website.

Required Parameters:

  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature) Alternatively, you may use an action token in place of a session token.

Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • disable_flash : To disable Flash uploads 'yes' or 'no'.
  • disable_html5 : To disable HTML5 uploads 'yes' or 'no'.
  • disable_instant : To disable instant uploads. Instant uploads works only when HTML5 uploads are enabled. 'yes' or 'no'.
  • action_on_duplicate : Specifies the action to take when the file already exists, by name, in the destination folder. skip ignores the upload, keep uploads the file and makes the file name unique by appending a number to it, and replace overwrites the old file, possibly adding to its version history. skip(default), keep, replace.
  • response_format : 'xml' or 'json' (default 'xml')

Response Properties

Name Description Type Value
error The numerical error code integer
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:

Example 1 (Success with JSON):

Request
http://www.mediafire.com/api/upload/set_options.php?disable_flash=yes&disable_instant=yes&session_token=01d8d27a6135e97bbda5a08bf37caf10be09e64acef0f60e56085bc96a22337e5f199d7a71cf0c6ee132003b7592a5dce45b73e3f79e915769e27c6ea3636cc1&hash=65dd21d705d5680cf7777286d627de9e799ef03e2ff0374df297382e3f1cd1d1&response_format=json
                        
Response
{
  "response": {
    "action": "upload/set_options",
    "result": "Success",
    "current_api_version": "1.3"
  }
}
                        

Simple


POST http://www.mediafire.com/api/1.3/upload/simple.php

Note: This API currently returns a Content-Type=text/xml header even when the response is in JSON format.

Description: Upload a new file through POST to the user's account. You can either use the session token to authenticate the user, or pass the FileDrop folder key. This API returns the upload key when successful. You will have to pass this key to upload/poll_upload to get the quickkey. Please refer to the documentation about the API upload/poll_upload for more details.

Required Parameters:


POST Body Data
  • The content(binary data) of the file to upload.

Header Data
  • Content-Type : Either "application/octet-stream" or "multipart/form-data + boundary".
(see Upload Guide for more details)

Relative Parameters:


URL Query Data
  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature) Alternatively, you may use an action token in place of a session token.
  • filedrop_key : A key representing a filedrop folder. Required if session_token is not passed. Ignored if folder_key is passed.
  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Header Data
  • x-filename : The name plus extension of the file to be created. The name should be 3 to 255 characters in length and UTF-8 encoded. Required and only used for Content-Type: "application/octet-stream".
  • x-filesize : The size, in bytes, of the binary file data. Required and only used for Content-Type: "application/octet-stream".

Optional Parameters:


URL Query Data
  • folder_key: The destination folder to store the file. If it's not passed, then the file will be stored in the root folder. Alternatively, you may pass myfiles as a folderkey moniker for the root folder.
  • path : An absolute or relative path to upload the file to. Absolute paths begin with a slash; relative paths do not and are in relation to the specified folder_key or filedrop_key. Non-existent folders will not be created by this call.
  • action_on_duplicate : Specifies the action to take when the file already exists, by name, in the destination folder. skip ignores the upload, keep uploads the file and makes the file name unique by appending a number to it, and replace overwrites the old file, possibly adding to its version history. The default is to use the user's preference set through upload/set_options. If the user has not set a default then skip is used. skip (default), keep, replace.
  • mtime : The date/time of the update. If not set, the current server time will be used. Refer to the following document for valid date/time formats: http://www.php.net/manual/en/datetime.formats.php
  • response_format : xml(default) or json.

Header Data
  • x-filehash : The SHA256 hash of the file being uploaded. Used to ensure data integrity. Hash is not case sensitive.

Response Properties

Name Description Type Value
result Numerical ID of checks done before any file data is actually transferred (this appears under the subheading 'doupload') integer 0(success), -10, -12, -26, -50, -54, -70, -80, -120-, 140, -200(internal server error), -14(destination does not exist), -31, -40(unknown upload error), -32(missing file data), -41(max file size exceeded), -42(max specified file size exceeded), -43(file partially uploaded), -44(no file uploaded), -45(missing a temporary folder), -46(failed to write file to disk), -47(a PHP extension stopped the upload), -48(invalid file size), -49(missing file name), -51(file size mismatch), -90(source hash mismatch), -203(invalid quickkey or file does not belong to session user), -204(session user lacks permission to patch file), -205(session user lacks permission to destination), -206(the destination has been deleted), -207(the uploaded file is not a valid patch file), -701, -881(max file size exceeded for free users), -700, -882(max file size exceeded)
key An alpha-numeric ID key used with upload/poll_upload to determine the status of the file upload (this appears under the subheading 'doupload') string
server The server type uploaded to string live
device_revision The revision of the device integer
error The numerical error code integer
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.

Examples:


Example 1 (Success with XML)

Request
HTTPS://www.mediafire.com/api/upload/simple.php?session_token=&filedrop_key=&response_format=xml&signature=
Response
<action>upload/simple</action>
<doupload>
   <result>0</result>
   <key>617cbd5e21829a53e133cd3bb1ad5d80</key>
</doupload>
<server>live</server>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>


Example 2 (Success with JSON - folder_key not owned by session user having edit permission)

Request
HTTPS://www.mediafire.com/api/upload/simple.php?session_token=&folder_key=8qkxzxu31sqe5&action_on_duplicate=keep&response_format=json&signature=
Response
{
   action: upload/simple,
   doupload:{
      result: 0,
      key: 068n326bzaw,
   }
   server: live,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}


Example 3 (Success with JSON - non-existent path)

Request
HTTPS://www.mediafire.com/api/upload/simple.php?session_token=&path=Folder003&action_on_duplicate=keep&response_format=json&signature=
Response
{
   action: upload/simple,
   doupload:{
      result: 0,
      key: 9h4c4cj9ebz,
   }
   server: live,
   device_revision: 160022,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}


Update


GET http://www.mediafire.com/api/1.3/upload/update.php
POST http://www.mediafire.com/api/1.3/upload/update.php

Note: This API currently returns a Content-Type=text/xml header even when the response is in JSON format.

Description: Update an existing file in the user's account with another file. This API returns the upload key when successful. You will have to pass this key to upload/poll_upload.php to check the final result of the update upload. Please refer to the documentation about the API upload/poll_upload for more details.

Required Parameters:


POST Body Data
  • The content(binary data) of the file to upload.
(see Upload Guide for more details)

URL Query Data
  • session_token : A type 1 or type 2 session token. (Type 2 will require a call signature). Required if not uploading to a FileDrop. Alternatively, a valid action token may be used instead.
  • quick_key : The quickkey of the file to update. The uploaded file content will be used to patch then override an existing file's current revision defined by the passed quickkey

Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:


URL Query Data
  • mtime : The date/time of the update. If not set, the current server time will be used. Refer to the following document for valid date/time formats: http://www.php.net/manual/en/datetime.formats.php
  • previous_hash : The hash of the last known version of the file before it was modified. If previous_hash does not match the cloud file's hash the file will be uploaded as a new file with a new quickkey and file name. Hash is not case sensitive.
  • response_format : xml(default) or json.

Response Properties

Name Description Type Value
result Numerical ID of checks done before any file data is actually transferred (this appears under the subheading 'doupload') integer 0(success), -10, -12, -26, -50, -54, -70, -80, -120-, 140, -200(internal server error), -14(destination does not exist), -31, -40(unknown upload error), -32(missing file data), -41(max file size exceeded), -42(max specified file size exceeded), -43(file partially uploaded), -44(no file uploaded), -45(missing a temporary folder), -46(failed to write file to disk), -47(a PHP extension stopped the upload), -48(invalid file size), -49(missing file name), -51(file size mismatch), -90(source hash mismatch), -203(invalid quickkey or file does not belong to session user), -204(session user lacks permission to patch file), -205(session user lacks permission to destination), -206(the destination has been deleted), -207(the uploaded file is not a valid patch file), -701, -881(max file size exceeded for free users), -700, -882(max file size exceeded)
key An alpha-numeric ID key used with upload/poll_upload to determine the status of the file upload (this appears under the subheading 'doupload') string
server The server type uploaded to string live
error The numerical error code integer
message The error description for error string
deprecated Indicates this API is deprecated and should no longer be used string
result Indicates if the API call was successful string Success or Error
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. flag yes
current_api_version The latest stable API version number string


Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:


Example 1 (Success with XML):

Request
HTTPS://www.mediafire.com/api/upload/update.php?session_token=&quickkey=4o1bd379kbc1bg2&previous_hash=&response_format=xml&signature=
Response
<action>upload/update</action>
<doupload>
   <result>0</result>
   <key>6dbpphc11z2</key>
</doupload>
<server>live</server>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>