Resource functions
Collection functions
Search functions
IIIF
Metadata functions
User functions
System
Message functions
Plugin functions

upload_multipart

Uploads files using HTTP multipart to an existing resource, replacing any file that is already attached.

Available from version 10.2+.

Variable Description Data type Default
$ref * The ID of the resource. integer N/A
$no_exif * Do not process embedded metadata. boolean N/A
$revert * Do not upload a new file, but re-process the existing file as if it has been uploaded again. Useful for re-processing embedded metadata, e.g. after changing the field mappings. boolean N/A
$file *

The file to upload.

Important: do not use the file as part of the signature!

 binary N/A

Response

If successful, a 204 HTTP status will be returned, otherwise different HTTP statuses with a payload message describing the issue.

Examples

General error (HTTP status - 500):

Array
(
    [status] => fail
    [data] => Array
        (
            [message] => An error occurred while uploading the file.
        )
)

File size too big error (HTTP status - 413):

Array
(
    [status] => fail
    [data] => Array
        (
            [message] => The maximum allowed upload file size is 5M.
        )
)

Duplicate file (HTTP status - 400):

Array
(
    [status] => fail
    [data] => Array
        (
            [message] => Duplicate file upload, file matches resources: 8
        )
)

Note: this requires checksums to be enabled.

Request example

PHP

// Set the private API key for the user (from the user account page) and the user we're accessing the system as.
$private_key = "your users' private key";
$user = "your username";
$url = "https://my.resourcespace.system/api/";

// Formulate the API binding (function) query data.
$data = array(
    'user'  => $user,
    'function'  => 'upload_multipart',
    'ref' => 8,
    'no_exif' => true,
    'revert' => false,
    );

// Sign the query using the private key.
$sign = hash('sha256', $private_key . http_build_query($data));

// This part simply replicates the GET query string to be POSTed as a single 'query' POST item.
$data['sign'] = $sign;
$postdata = [
    'query' => http_build_query($data),
    'sign' => $sign,
    'user' => $user,
    'file' => new CURLFile('/path/to//file.ext'), # IMPORTANT: this wasn't part of the signature!
];

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: multipart/form-data']);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1 );

// Make the request and output the results.
$curl_response = curl_exec($curl);
print_r(json_decode($curl_response));

cURL

# Generate the signature for the request
echo -n "yourPrivateKeyuser=yourUsername&function=upload_multipart&ref=1126&no_exif=1&revert=0" | sha256sum
curl \
    -F 'query="user=yourUsername&function=upload_multipart&ref=1126&no_exif=1&revert=0"' \
    -F 'sign="yourGeneratedSignature"' \
    -F 'user="yourUsername"' \
    -F "file=@/path/to/file.ext" \
    'https://localhost/trunk/api/'