Getting Started1.0

Frequently Used Terms

Below is a list of Frequently Used Terms used throughout this documentation. Any terms specific to MediaFire will be hyperlinked back to this page for further explanation.

quickkey: quickkey is a reference to a file. You can get quickkeys from /folder/get_content.

folderkey: folderkey is a reference to a folder. You can get a list of folderkeys from /folder/get_content. When you use the /folder/get_content API without a folder key defined, it will automatically give you the folderkeys for the folders in your root 'My Files' page. From there, you can retrieve the folderkey of the folder you would like to continue "digging into". Next, update the 'get_content' folder url with the folderkey you would like to inspect. This process can be repeated continually until you reach your desired folderkey.

session token: session token is a token used to authorize user specific transactions. You can get instructions for obtaining a session token at /user/get_session_token.

web upload: a web upload is when you give MediaFire a URL of an item you would like placed in your account. In return, Mediafire will download the file from the specified URL and place it directly into your My Files (unless you specify a different folderkey). For example: if you give MediaFire the URL www.mediafire.comimages/contact_trie.jpg we will fetch contact_trie.jpg and download it into your account. This is an ideal situation to obtain a file for your account without you having to use your bandwidth to access it.

Best Practices

Below is a list of suggested measures which will ensure your code is using the MediaFire REST API in a more efficient and secure manner:

• DO use Session Token 2 over type 1.
• DO use Resumable Uploads.
• DO use Action Tokens when fetching large numbers of images using the the Media API and Image Conversion systems.
• DO use restrictive security features, such as restrictions by Domains, IP Addresses, and Callback URLs, to improve security for web applications.
• DO attempt to use the Instant Upload feature.
• DO destroy Action Tokens when they are no longer necessary.
• DO use SSL whenever possible.
• DO use the POST request method instead of GET whenever possible.
• When performing an upload, DO use Action Tokens to improve performance.
• When performing an upload, DO ensure the account you are uploading to has adequate space for the file.
• DO NOT expose your API keys (when possible).

API Basics

Call Signature (Session Token 2)

Note: When making an API call using the GET request method, it is permissible to URL-encode the query string. The server will compute the Call Signature with both permutations (encoded and not encoded) looking for a match.

Description: The API call signature is required when Session Token version 2 is used. When you call the secure API user/get_session_token and supply 'token_version=2', in addition to 'session_token' you will receive two more values: 'secret_key' and 'time'. You will need these values in order to construct a signature to be passed along to any subsequent API calls.

The signature = the Message-Digest (MD5) of the 'secret_key' modulo 256 + 'time' + the URI of the API call.

The URI of the call is the URL excluding the signature and the hostname (e.g. "/1.0/file/get_info.php?quick_key=abcdefghijklmno").

After each API call that returns in the response new_key=yes, you will need to generate a new secret_key to use in the construction of the signature for the next API call. The generation of this new key is based on the MINSTD variant of a Linear Congruential Generator (LCG). The formula to use is: New Key = (Old Key * 16,807) modulo 2,147,483,647.

Obtaining an App ID and API Key

In order to build a signature, you will need to create an app with a unique ID and key. If you do not already have this information, follow these steps:

• From MediaFire, visit your Account Settings page.
• Choose "Developers" from the sidebar menu.
• If you have never created an app before, fill in the requested information and click "Submit".
• You may need to validate your email address before continuing.
• Enter a name for your app and click "Create New Application".
• Copy the generated app ID and API key from the table below.

https://www.mediafire.com/api/1.0/user/get_session_token.php?email=some_email@domain.com&password=123456&application_id=9999&signature=0123456789012345678901234567890123456789&token_version=2

<response>
 <action>user/get_session_token</action>
 <session_token>
  01234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789

 </session_token>
 <secret_key>9316931</secret_key>
 <time>1359061000.8125</time>
 <result>Success</result>
 <current_api_version>1.0</current_api_version>
</response>
                        

Making a first call using this Session Token

Let's make a call to get the user's personal info. Our API call URI is : /api/1.0/user/get_info.php?session_token=[insert session token here] Therefore, we construct the signature by concatenating the Secret key modulo 256, Time and the URI, then apply MD5 on the result. 9316931 modulo 256 is 67. This will be calculated as follows: signature = MD5('671359061000.8125/api/1.0/user/get_info.php?session_token=[insert session token here) The signature is 938a3a05ba087245fc2c7f96512cdbd8 and the API call would be:
http://www.mediafire.com/api/1.0/user/get_info.php?session_token=[insert sample token here]&signature=[insert signature here]

Making a second call using this Session Token
Once a signature is created, the secret key is no longer usable for generating a call signature. However, the developer will still need to old secret key to generate a new secret key. The New key is calculated as follows: new key = (9316931 * 16807) modulo 2147483647 which is 1970836733 We will make a call to get the root folder's content. Our URI will be: /api/1.0/folder/get_content.php?session_token=[insert session token here]&content_type=files
Next, we construct the signature using the new key. 1970836733 modulo 256 is 253. This is calculated as follows: signature = MD5('2531359061000.8125/api/1.0/folder/get_content.php?session_token=[insert session token here]&content_type=files') The signature is 7b3faa54b895254aaff9f5caa30e25a4 and the API call would be:
http://www.mediafire.com/api/1.0/folder/get_content.php?session_token=[inset session token here]&content_type=files&signature=7b3faa54b895254aaff9f5caa30e25a4

We continue generating a new secret key for every API call as long as the previous API call returns 'new_key' data set to 'yes'.

Asynchronous Job Queue

Some API calls require extended processing time, for example copying a folder that has several hundred items in it. For those API calls, the API won't block for the operation to complete, but returns immediately and the operation is performed in the background as an asynchronous job. The API response then returns asynchronous=yes. However, copying a folder with few items in it will be performed synchronously and the API returns asynchronous=no. If an API doesn't return the meta tag asynchronous, the operation is always performed synchronously. Some of the API calls that might be performed asynchronously include, but are not limited to:

• folder/copy
• folder/delete
• folder/move
• folder/purge, and
• folder/update

Example - Purging a folder with 700 nested folders and files in it (permanent deletion):

http://www.mediafire.com/api/1.0/folder/purge.php?session_token=70544260fc2ad423bffc0d2d446719c32db7758d6c38d8b6a78d13d6158cf29e2491a05c2c0c023140a0c04471c95a263d1fefbb3a125ac734181daec640d690ca6cabac774c5a1c&folder_key=618o4cknwzyak

<response>
 <action>folder/purge</action>
 <asynchronous>yes</asynchronous>
 <result>Success</result>
 <current_api_version>1.0</current_api_version>
</response>
                        

HTTP Status Codes

The API returns, as part of the response headers, a HTTP Status code. If the API call succeeds, a 200 OK is always returned. In case of an error, a different code is returned and an API response body is still returned. The following is a list of possible HTTP codes.

• 200 OK
• 400 Bad Request
• 403 Forbidden
• 404 Not Found
• 900 Internal Server Error

Authentication Widget

Instead of handling user credentials yourself, MediaFire supports an OAuth-style login flow.

First, a small (<1KB) JS file should be included in your page.

https://github.com/MediaFire/mediafire-javascript-sdk

This exposes a global function: MF.login(options, callback, scope)
The options parameter should be an object consisting of the fields apiKey and apiID.
Those fields should contain your application key and application id, respectively.
The second parameter is your callback, which will be called when the session token is available. The session token will be the first argument in the callback.
You may optionally specify a scope, which will override the context of the "this" keyword in the callback.

Example

http://www.mediafire.com/auth/mediafire_login.js

<!doctype html>
<html lang="en">
<head>
 <title>Login Test</title>
 <script src="https://www.mediafire.com/auth/mediafire_login.js"></script>
</head>
<body>
 <button onclick="login();">Login</button>
 <script>
  var options = {

   apiID: 9001

  };

 

  function login() {

   MF.login(options, function(sessionToken) {

    alert(sessionToken);

   });

  }

 </script>
</body>
</html>
                        

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:

POST http://www.mediafire.com/api/1.0/upload/upload.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.

Error Codes

Below is a list of errors you may incur and their definition:

• 101 : ERROR_INTERNAL: Internal server error.
• 102 : ERROR_MISSING_KEY: API Key is missing.
• 103 : ERROR_INVALID_KEY: The supplied API Key is invalid.
• 104 : ERROR_MISSING_TOKEN: Session Token is missing.
• 105 : ERROR_INVALID_TOKEN: The supplied Session Token is expired or invalid.
• 106 : ERROR_CHANGE_EXTENSION: You cannot change the file extension by changing the file name.
• 107 : ERROR_INVALID_CREDENTIALS: The Credentials you entered are invalid.
• 108 : ERROR_INVALID_USER: Unknown or invalid user.
• 109 : ERROR_INVALID_APPID: Unknown or invalid Application ID.
• 110 : ERROR_INVALID_QUICKKEY: Unknown or Invalid QuickKey.
• 111 : ERROR_MISSING_QUICKKEY: Quick Key is missing.
• 112 : ERROR_INVALID_FOLDERKEY: Unknown or invalid FolderKey.
• 113 : ERROR_MISSING_FOLDERKEY: Folder Key is missing.
• 114 : ERROR_ACCESS_DENIED: Access denied.
• 115 : ERROR_FOLDER_PATH_CONFLICT: Cannot move/copy a Folder to itself or to one of its Sub-Folders.
• 116 : ERROR_INVALID_DATE: The date specified is not valid.
• 117 : ERROR_MISSING_FOLDERNAME: Folder Name is missing.
• 118 : ERROR_INVALID_FILENAME: The File Name specified is invalid.
• 119 : ERROR_NO_MF_EMAIL: You cannot register a Mediafire.com email address.
• 120 : ERROR_EMAIL_TAKEN: The email address you specified is already in use.
• 121 : ERROR_EMAIL_REJECTED: The email address you specified is found to be rejected/bounced.
• 122 : ERROR_EMAIL_MISFORMATTED: The email address you specified is misformatted.
• 123 : ERROR_PASSWORD_MISFORMATTED: The password you specified is misformatted.
• 124 : ERROR_API_VERSION_MISSING: The API Version is missing.
• 125 : ERROR_OLD_API_VERSION: The API version specified or the API Library is old for this call. Please Specify a higher API version or update your API Library.
• 126 : ERROR_API_CALL_DEPRECATED: This API call has been deprecated for the API version specified or the API Library. Please refer to the API documentation for alternative calls.
• 127 : ERROR_INVALID_SIGNATURE: The signature you specified is invalid.
• 128 : ERROR_MISSING_PARAMS: Required parameters for this request are missing.
• 129 : ERROR_INVALID_PARAMS: One or more parameters for this request are invalid.
• 130 : ERROR_NON_PRO_LIMIT_REACHED: Non premium account limitation reached.
• 131 : ERROR_ADD_OWNED_FOLDER: Cannot add a shared folder to its owner's account.
• 132 : ERROR_REMOVE_OWNED_FOLDER: Cannot remove a shared folder from its owner's account.
• 133 : ERROR_ADD_ANON_FOLDER: Cannot add a shared folder from an anonymous account.
• 137 : ERROR_CONTACT_ALREADY_EXISTS: This contact already exists in the user's contact list.
• 138 : ERROR_CONTACT_DOES_NOT_EXIST: This contact does not exist.
• 139 : ERROR_CONTACT_GROUP_EXISTS: This group already exists in the user's contact list.
• 140 : ERROR_UNKNOWN_CONTACT_GROUP: This group does not exist.
• 141 : ERROR_UNKNOWN_DEVICE: Unknown or invalid device.
• 142 : ERROR_INVALID_FILE_TYPE: Unsupported or invalid file type.
• 143 : ERROR_FILE_ALREADY_EXISTS: This file already exists.
• 144 : ERROR_FOLDER_ALREADY_EXISTS: This folder already exists.
• 145 : ERROR_APPLICATION_DISABLED: The application trying to access the API is disabled.
• 146 : ERROR_APPLICATION_SUSPENDED: The application trying to access the API is suspended.
• 147 : ERROR_ZIP_MULTIPLE_OWNERS: Bulk downloading from multiple file owners is currently not supported.
• 148 : ERROR_ZIP_NON_PRO_DOWNLOAD: Bulk download requires the file owner or the downloader to be premium.
• 149 : ERROR_ZIP_OWNER_NOT_PRO: The owner of the files is not a premium user. You need to confirm the download using your own bandwidth.
• 150 : ERROR_ZIP_FILE_TOO_BIG: One or more files are too large to be included. Files must be X MB or less in order to be included in the zip file.
• 151 : ERROR_ZIP_NO_FILES_SELECTED: The item you selected contained no files. You must select at least one file to zip.
• 152 : ERROR_ZIP_NO_FILES_ZIPPED: None of the selected files were able to be zipped at this time.
• 153 : ERROR_ZIP_TOTAL_SIZE_TOO_BIG: The total size of the zip file is larger than X MB. You need to confirm the download.
• 154 : ERROR_ZIP_NUM_FILES_EXCEEDED: Maximum number of files reached. Cannot add more than X files.
• 155 : ERROR_ZIP_OWNER_INSUFFICIENT_BANDWIDTH: The files owner does not have enough bandwidth to download the zip file. You need to confirm the download using your own bandwidth.
• 156 : ERROR_ZIP_REQUESTER_INSUFFICIENT_BANDWIDTH: You do not have enough bandwidth to download the zip file.
• 157 : ERROR_ZIP_ALL_INSUFFICIENT_BANDWIDTH: Neither the owner of the files nor you have enough bandwidth to download the zip file.
• 158 : ERROR_FILE_EXISTS: This file exists already.
• 159 : ERROR_FOLDER_EXISTS: This folder exists already.
• 160 : ERROR_INVALID_ACCEPTANCE_TOKEN: The Terms of Service acceptance token is invalid.
• 161 : ERROR_USER_MUST_ACCEPT_TOS: You must accept the latest Terms of Service.
• 162 : ERROR_LIMIT_EXCEEDED: The file(s)/folder(s) you upload/copy exceed your total storage limit.
• 163 : ERROR_ACCESS_LIMIT_REACHED: You have reached the limit accessing the API. Please try again later.
• 164 : ERROR_DMCA_ALREADY_REPORTED: These files have already been reported.
• 165 : ERROR_DMCA_ALREADY_REMOVED: These files no longer exist in our system.
• 166 : ERROR_ADD_PRIVATE_FOLDER: Cannot add a private folder to an account.
• 167 : ERROR_FOLDER_DEPTH_LIMIT: Maximum depth of folder reached. Cannot add more than X nested folders.
• 168 : ERROR_INVALID_PRODUCT_ID: Invalid Product Id.
• 169 : ERROR_UPLOAD_FAILED: Upload Failed.
• 170 : ERROR_TARGET_PLAN_NOT_IN_THE_SAME_CLASS: Can't change plan to one that is not in the same class with the current.
• 171 : ERROR_BIZ_PLAN_RESTRICTION: Can't change plan from/to business plan.
• 172 : ERROR_EXPIRATION_DATE_RESTRICTION: Can't change plan, plan will be expiring or it has already expired.
• 173 : ERROR_NOT_PREMIUM_USER: Must be a premium user to use this function.
• 174 : ERROR_INVALID_URL: The URL specified is invalid.
• 175 : ERROR_INVALID_UPLOAD_KEY: The Upload Key specified is invalid.
• 176 : ERROR_STORAGE_LIMIT_RESTRICTION: The storage amount for this product is less than the total size of your files.
• 177 : ERROR_DUPLICATE_ENTRY: Cannot insert a duplicate entry.
• 178 : ERROR_PRODUCT_ID_MATCH: Cannot change to same plan.
• 179 : ERROR_NOT_CURRENT_PRODUCT: Must change to a current product.
• 180 : ERROR_BIZ_DOWNGRADE: Cannot downgrade from a business account.
• 181 : ERROR_BUSINESS_UPGRADE: Error upgrading to business account.
• 182 : ERROR_CHANGE_PLAN_CREDIT: You do not have enough credit to change to this plan. Please contact customer service.
• 183 : ERROR_BANDWIDTH_ERROR: Changing to this product would give you negative bandwidth.
• 184 : ERROR_ALREADY_LINKED: The account you are trying to link is already linked to another MediaFire user.
• 185 : ERROR_INVALID_FOLDERNAME: The specified Folder Name is invalid.
• 186 : ERROR_ZIP_PASSWORD_BULK: Cannot download password-protected files in bulk.
• 187 : ERROR_SERVER_NOT_FOUND: Found no server matching your request.
• 188 : ERROR_NOT_LOGGED_IN: You must be logged in to purchase a plan.
• 189 : ERROR_RESELLER_TOS: You must agree to the reseller terms of service.
• 190 : ERROR_BUSINESS_SEAT: Business seats cannot make purchases.
• 191 : ERROR_BANNED_BUYER: This user is a banned buyer.
• 192 : ERROR_RESELLER_CREDITS_ERROR: Error with reseller credits.
• 193 : ERROR_PURCHASE_BANNED_ERROR: You may not purchase from this country.
• 194 : ERROR_SUBDOMAIN_ERROR: The subdomain is in use or invalid.
• 195 : ERROR_TOO_MANY_FAILED: This user has too many failed transactions.
• 196 : ERROR_INVALID_CARD: The credit card you have entered is invalid.
• 197 : ERROR_RECENT_SUBSCRIBER: You have purchased an account within the last 3 days.
• 198 : ERROR_INVOICE_FAILED: There was an error storing the invoice.
• 199 : ERROR_DUPLICATE_API_TRANSACTION: A duplicate transaction has been submitted.
• 200 : ERROR_CARDCCV_ERROR: Invalid card CCV code
• 200 : Invalid card CCV code.
• 201 : ERROR_TRANSACTION_DECLINED: This transaction has been declined.
• 202 : ERROR_PREPAID_CARD: Prepaid card error.
• 206 : ERROR_CARD_STORE_FAILED: There was an error storing the credit card.
• 207 : ERROR_COPY_LIMIT_EXCEEDED: Total number of files copied cannot exceed "(MAX_OBJECTS, HTTP_STATUS_FORBIDDEN).
• 208 : ERROR_ASYNC_JOB_IN_PROGRESS: Another Asynchronous Operation is in progress. Please Retry later.
• 209 : ERROR_FOLDER_ALREADY_DELETED: This folder has already been deleted.
• 210 : ERROR_FILE_ALREADY_DELETED: This file has already been deleted.
• 211 : ERROR_CANT_MODIFY_DELETED_ITEMS: Items in the Trash Can cannot be modified.
• 212 : ERROR_CHANGE_FROM_FREE: You cannot change from a free plan.
• 214 : ERROR_INVALID_FILEDROP_KEY: The specified FileDrop Key is invalid.
• 215 : ERROR_MISSING_SIGNATURE: The call signature is missing.
• 216 : ERROR_EMAIL_ADDRESS_TOO_SHORT: The email address provided must be greater than 3 characters.
• 217 : ERROR_EMAIL_ADDRESS_TOO_LONG: The email address provided must be less than 50 characters.
• 218 : ERROR_FB_EMAIL_MISSING: Cannot register via Facebook. The Facebook Email is missing.
• 219 : ERROR_FB_EMAIL_EXISTS: The Facebook Email is already registered with a MediaFire account.
• 220 : ERROR_AUTH_FACEBOOK: Failed to authenticate to Facebook.
• 221 : ERROR_AUTH_TWITTER: Failed to authenticate to Twitter.
• 223 : ERROR_INVALID_REVISION: The revision you requested is invalid or cannot be restored.
• 224 : ERROR_NO_ACTIVE_INVOICE: There is no active invoice to cancel.
• 225 : ERROR_APPLICATION_NO_LOGGING: This application is not allowed to log to the database.
• 226 : ERROR_INVALID_INSTALLATION_ID: Invalid installation ID.
• 227 : ERROR_INCIDENT_MISMATCH: The provided incident and installation ID's do not match.
• 228 : ERROR_MISSING_FACEBOOK_TOKEN: The Facebook Access Token is required.
• 229 : ERROR_MISSING_TWITTER_TOKEN: The Twitter OAuth Token is required.
• 230 : ERROR_NO_AVATAR: This user has no associated avatar image.
• 231 : ERROR_INVALID_SOFTWARE_TOKEN: The provided software token is invalid.
• 232 : ERROR_EMAIL_NOT_VALIDATED: The email address of the sender is not yet validated.
• 233 : ERROR_AUTH_GMAIL: Failed to authenticate to Google.
• 234 : ERROR_FAILED_TO_SEND_MESSAGE: Failed to send message.
• 235 : ERROR_USER_IS_OWNER: You own this resource.
• 236 : ERROR_USER_IS_FOLLOWER: You already follow this resource.
• 237 : ERROR_USER_NOT_FOLLOWER: You are not following this resource.
• 238 : ERROR_UPDATE_NO_CHANGE: This file has not changed; no need to update.
• 239 : ERROR_SHARE_LIMIT_REACHED: Maximum number of allowed share for this resource is reached.
• 240 : ERROR_CANNOT_GRANT_PERMS: Cannot grant permissions to the specified resource(s).
• 241 : ERROR_INVALID_PRINT_SERVICE: The service number provided is not a recognized service.
• 242 : ERROR_FOLDER_FILES_EXCEEDED: The folder trying to be deleted has over 1000 files.
• 243 : ERROR_ACCOUNT_TEMPORARILY_LOCKED: This account is temporarily locked. Please, try again later.
• 244 : ERROR_NON_US_USER: This service is available to US residents only.
• 245 : ERROR_INVALID_SERVICE: You do not have permissions to access this Service.
• 246 : ERROR_CHANGE_FROM_AFFILIATE: You cannot change from a plan purchased through an affiliate.
• 247 : ERROR_CHANGE_FROM_APPLE: You cannot change from a plan purchased through the App Store.
• 248 : ERROR_APP_NOT_AUTHENTICATED: Unable to authenticate app.
• 249 : ERROR_INVALID_RECEIPT_DATA: Invalid receipt data submitted.
• 250 : ERROR_INVALID_TRANSACTION_ID: Transaction ID not found in receipt data.
• 251 : ERROR_USED_TRANSACTION_ID: This transaction ID has already been redeemed.
• 252 : ERROR_TOKEN_ALREADY_UPGRADED: The passed session token is already an upgraded version.
• 253 : ERROR_UNKNOWN_API: Unknown or invalid API method.
• 254 : ERROR_LIST_ALREADY_EXISTS: This Meta List name already exists.
• 255 : ERROR_UNKOWN_LIST: Unkown or Invalid Meta List.
• 256 : ERROR_INVALID_IMPORT_SERVICE: Invalid import service.
• 257 : ERROR_CARD_REUSE_FORBIDDEN: This client does not have permission to reuse credit card information.