API Reference

Uploading Files

Chunk Uploading using Multi Part Uploading API - used for large files (5MB minimum size) - Example
Services Used
        //Use split command to chunk file for uploading
        $arguments['fileData']=Array('title'=>"Gothia Cup Promo Video", "message"=>"World's largest youth soccer tournament happens yearly in Gothenburg, Sweden");

        //We start at one to avoid 0 index, which Amazon doesn't appreciate
        $cnt = 1;

        foreach (scandir('.') as $chunk) {
        if(preg_match("/^x.*/", $chunk)) {
        $uploadInfo = performApiCall($arguments);

        $mediaId = $uploadInfo['result']['id'];
        echo "Media ID is $mediaId\n";

        foreach($uploadInfo['result']['partUrls'] as $url) {
        echo "Uploading part {$filePart[$url['part']]} to {$url['url']}\n";
        putPart($url['url'], $filePart[$url['part']]);


        $completedInfo = performApiCall($doneArgs);


        function putPart($url,$file) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_PUT, 1);
        $fh_res = fopen($file, 'r');
        curl_setopt($ch, CURLOPT_INFILE, $fh_res);
        curl_setopt($ch, CURLOPT_INFILESIZE, filesize($file));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        $response = curl_exec ($ch);
        return $response;
        function performApiCall( $arguments) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_URL, APIENDPOINT);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($arguments));
        curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        $response = curl_exec($ch);
        return json_decode($response,1);


Legacy Method

The file upload is done through the means of a standard HTTP multipart POST request. The request should include a Content-type header with a value of multipart/form-data. NOTE: If you want to build a batch upload you need to call the upload multiple times, with each file, and each piece of media information.

The endpoint is located at   /services/upload2


There are two modes for uploading, one for uploads coming from another server and the other for uploading straight from a browser.

In the case you are uploading from a server, use your API key, otherwise a session token is required. You can acquire a session token through the users.getSessionToken or users.confirmCredentials methods, depending on your needs.

Redirect url

If you specify the redirect parameter, the user will be redirected automatically back to that URL with the mf_status parameter added (which will be 0 for failed, 1 for success).

In addition, the URL will include mf_id, which contains the ID of the uploaded file. If there was an error, the URL will include mf_error with an error message.

Moderation Status

If a moderationstatus parameter is provided then media.setModerationStatus will be called to update the new media item's moderation status after it has been uploaded successfully. If no moderation status is specified then the newly uploaded item will be marked as unmoderated and media.setModerationStatus will not be called.


Its often useful to add custom metadata to a file. This can be achieved using the meta property. The properties have to be added using php-style arrays. An example would be   meta[category]=myCategory. You can add as many properties as you'd like.

HTML Example

      <form action="http://api.newspark.ca/services/upload2"
         Title:<input type="text" name="title"><br/>
         Message:<input type="text" name="message"><br/>
         <input type="hidden" name="vhost" value="206">
         <input type="hidden" name="hidden" value="HIDDEN">
         <input type="hidden" name="uid" value="802456">
         <input type="hidden" name="meta[user][name]" value="Dave">
         <input type="hidden" name="meta[user][address]" value="18mowat">
         <input type="hidden" name="APIKEY" value="<?$_REQUEST['sessionToken']?>">
         <input type="FILE" name="file">
         <input type="submit">

PHP Example

$post = array(
   'title'=>"This is the title of the media",
   'message'=>"this is the description of the media",
   'tags'=>"tag1 tag2 tag3",

if ((version_compare(PHP_VERSION, '5.5') >= 0)) {
    $post['file_box'] = new CURLFile('/tmp/localfile.jpg');
    curl_setopt($ch, CURLOPT_SAFE_UPLOAD, true);
} else {
    $post['file_box'] = '@/tmp/localfile.jpg';

$ch = curl_init();

  curl_setopt($ch, CURLOPT_URL,"http://api.newspark.ca/services/upload2");
  curl_setopt($ch, CURLOPT_HEADER, 0);
  curl_setopt($ch, CURLOPT_VERBOSE, 0);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERAGENT, "Mozilla/4.0 (compatible;)");
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
  $response = curl_exec($ch);

C# Example

using System;
using System.IO;
using System.Net.Http;

namespace test.api
   class Upload
      public static void Main(string[] args)
         var requestContent = new MultipartFormDataContent();
         requestContent.Add(new StringContent("VHOSTID"), "vhost");
         requestContent.Add(new StringContent("YOURAPIKEY"), "APIKEY");
         requestContent.Add(new StringContent("USERID"),"uid");
         var client = new HttpClient();

         var path = @"test.jpg"; 
         FileStream fs = File.OpenRead(path);
         var streamContent = new StreamContent(fs);
         streamContent.Headers.Add("Content-Type", "application/octet-stream");
         requestContent.Add(streamContent, "file", Path.GetFileName(path));

         var hResult = client.PostAsync("http://api.newspark.ca/services/upload2?json", requestContent).Result;
         var sResult = hResult.Content.ReadAsStringAsync().Result;
         Console.WriteLine( sResult.ToString());



Name Type Required Default Value Description
vhost INT Required none The vhost ID that you are uploading into.
uid INT Optional none The ID of the user who is uploading the media.
title STRING Optional none The title of the media item being uploaded.
message STRING Optional none The description of the media item being uploaded.
tags STRING Optional none A set of words used to tag the media item. Tags are searchable in our system. Each tag is separated by a space — for example "upload media torontoweather toronto".
parentid INT Optional none The media id that you'd like to be the parent of this media.
context INT Optional 1 The context of the media item. This will be used to determine if the media item is a comment, note, parent media etc.
channel INT Optional none The channel ID of the media item is going to be uploaded into.
channelshortname STRING Optional none The channel shortname of the media item is going to be uploaded into.
APIKEY STRING Optional none The developer API Key supplied by Filemobile to the developer. This key should NEVER be forward facing to the public.
uploadToken STRING Optional none You can generate the uploadToken using the users.getSessionToken method. If you are logged in or have an API Key, you don't need an uploadToken
sessiontoken STRING Optional none The current user Session Key. The Filemobile session toke namen is 'SABRE_ID'.
redirect STRING Optional none The URL we will redirect the user to once the upload is complete.
meta array Optional none Use this to include additional custom information about the file when uploaded.
moderationstatus INT Optional none, see note The moderation status that will be assigned to the media item once the upload is complete. The moderation status must be supported by media.setModerationStatus.
event INT / ARRAY Optional 0 An event ID or an array of event ID's that the media item will be inserted into. To specify that the media should _NOT_ be added to an event set this value as 0.
group INT / ARRAY Optional 0 A group ID or an array of group ID's that the media item will be inserted into. To specify that the media item should _NOT_ be added to a group set this value as 0.


The response is returned back once the upload is complete. The reponse from /services/upload2 is formatted XML with the same information returned from the media.getFileInfo service call. The sample of the XML response is listed below.

Name Description Possible Values
id The media ID of the newly uploaded media. INT
status The upload status of the newly uploaded media item. 0,1,2,3
contenttype The mimetype of the new file. For example: audio/mp3. MIMETYPE
filetype The filetype of the new media item. 0,1,2,3,4
context The context of the media item. This will be used to determine if the media item is a comment, note, parent media etc. 0,1,2,3
filename The original file name of the new media item. string/empty
injector The origin of the uploaded piece of media. MediaFactory,email
hits The number of views the media received. INT
message The description of the media item. STRING
date The date and time the file started to be uploaded into MediaFactory. YYYY-MM-DD HH:MM:SS
title The title of the media item. STRING
tags The tags associated with the media item. Each tag is seperated by a space (ex. " "). STRING
extension The original file extension of the uploaded media item. An example would be png, mov etc. STRING
sender DEPRECATED empty
author DEPRECATED empty
metadata The metadata that is stored with the media item. This is returned in associated array. Metadata
uid The ID of the user who uploaded the media. INT
filesize The size of the media item in our system. The size is returned in bytes. INT
ofilesize The original filesize before being converted in our system in KB. INT
upload The upload date of the media. The date formated in the following pattern YYYY-MM-DD HH:MM:SS. YYYY-MM-DD HH:MM:SS
location The server location of the uploaded media item. STRING (s3, fmlocal, fmdevs3)
originallocation The location of where the original file is stored. s3, fmlocal, fmdevs3
moderationstatus The current moderation status of the file. 0,1,2,3,-1
width The original width of the file in pixels. INT
height The original height of the file in pixels. INT
length The duration of the file in as a floating point number in seconds. (example: 187.33, for 3 minutes, 7 seconds) NUMBER
conversiontime The time it took to convert the file. INT(seconds)
converttime The date and time the transcoding of the file was completed. YYYY-MM-DD HH:MM:SS
lastupdatetime The date and time of the last update which was made to the file. YYYY-MM-DD HH:MM:SS
rating The rating of the file. INT
votecount The vote count of the file. INT
externalid This is used to reference the ID of the file if it is hosted by one of our partners. An example is for MMComments ( Brightcove ) STRING
parentid The parent ID of the media item. This would be specified if the media item was a comment. This would be the ID of the media which the commented was made on. INT
user_name The user name of the submitter. STRING
user_email The email of the submitter. STRING
user_country The 2-letter country code of the submitter. STRING
user_city The city of the submitter. empty,STRING
user_state The 2-letter state or province code of submitter. STRING
user_nickname The submitter's nickname. STRING
user_firstname The submitter's firstname. empty,STRING
user_lastname The last name of the user who uploaded the file. STRING
url A url that is associated with the media being uploaded. STRING
vhost The ID of the vhost which the file belongs to. INT
language The 2-character ISO language code. STRING
channel The channel ID the file is a member of. INT
channel_shortname The channels given short name that the file is a member of. STRING (sample_shortname)
channel_name The channel name the file belongs to. STRING
channelleft The channel position from the left of the channel tree. (For internal purposes.) INT
geo_latitude The latitude of the file. This is added via dropping the pin on the map upon upload. NUMBER (62.86)
geo_longitude The longitude of the file. This is added via dropping the pin on the map upon upload. NUMBER (-52.44)
hidden The visibility of the file. HIDDEN, SHOWN, or ALL
commentcount The total number of comments made on the file. INT
approvedcomments The total number of approved comments made on the file. INT
notdeniedcomments The total number of not denied comments made on the file. INT
publicUrl The publically accessible url of the media item. This url _WILL_ log a hit on the piece of media when the meida is loaded. STRING
thumbUrl The publically accessable url to be used for thumbnails only. Using the thumbUrl will _NOT_ log a hit on the media item. STRING
moderationdeniedid The moderation reason for being denied.Possible values for denied reasons are 0-14. 0-14. Exact reasons are avaiable in our glossary.
conversions An array of the completed file conversions made for the piece of media. conversion statustranscoder profile ID.
isLive Returns if the media was uploaded and if the media item is currently live. true, false

Example Formatted REST Response

<?xml version="1.0" encoding="UTF-8"?>
  <date>2012-01-26 11:29:26</date>
  <upload>2012-01-26 11:29:26</upload>
  <lastupdatetime>2012-01-26 11:29:26</lastupdatetime>

Example Formatted JSON Response

Add "?json" to the call to get the response via json :     /services/upload2?json


Be the first to comment on Uploading Files.

Add a Comment

  • captcha