Upload a file

To upload a file you access the /apiv2/uploadservice/upload endpoint and supply the file contents in a HTTP POST request. Each request is limited to maximum 4Mb of data so if the file to be uploaded is larger it need to be posted in multiple requests. (There is no minimum upload file so segments can be less in size if need be.)

First upload request

When the first request is issued, it responds with an uploadFileId. The uploadFileId is used in the following upload requests and when storing the uploaded file in ImageVault. Use application/octet-stream as content type for upload requests and post the file contents as binary data.

Following upload requests

If file needs to be uploaded in multiple requests the uploadFileId is used in the url of the following posts on the format /apiv2/uploadservice/upload/uploadFileId. Each following request will be appended to the uploaded file

Storing the file in ImageVault

After all parts of the file has been uploaded, call the /apiv2/mediacontentservice/storecontentinvault and supply the filename, content type, uploadFileId and the id of the Vault that it should be placed in. Observe that the user uploading the image needs to have atleast Contribute access to the vault in question. Read more about the StoreContentInVault method in the API reference.

Mark media as ready to use

Now the item is stored in ImageVault but not yet visible to the users. It is in an “Unorganized mode” that indicates that it has not yet been processed by an user (the organize view). You can use this step to either set own metadata or add some user interaction or do nothing at all. When done, mark the item as ready to use by calling the /apiv2/mediaservice/save method and supply the saveOption MarkAsOrganized.

Note

You can store metadata and categories in the same Save call. Just supply them in the mediaItem and bitwize add those flags to the saveOption.

Read more about the Save method in the API reference.

Example

The example will upload a text file with two lines wich each line in different upload requests. Authentication has already been performed and we have an existing authorization token.

First upload request

This will initiate the upload and upload the first part of the file.

POST http://imagevaultui.local/apiv2/uploadservice/upload HTTP/1.1
Authorization: Bearer mi3hxynuho7s0j8sf8a0
X-Requested-With: XMLHttpRequest
Content-Type: application/octet-stream
Host: imagevaultui.local
Content-Length: 30
Expect: 100-continue

This is the first row of data

First upload response

The response will contain an upload id that should be used in the following upload sessions

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 22

"eSb9GNFURwVgKuJMpsmf"

Second upload request

The upload id is appended to the url of the upload service to indicate that the supplied data should appended to the first uploaded segment

POST http://imagevaultui.local/apiv2/uploadservice/upload/eSb9GNFURwVgKuJMpsmf HTTP/1.1
Authorization: Bearer mi3hxynuho7s0j8sf8a0
X-Requested-With: XMLHttpRequest
Content-Type: application/octet-stream
Host: imagevaultui.local
Content-Length: 31
Expect: 100-continue

This is the second row of data

Second upload response

The response will return the same upload id as an indication that it has appended the data

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 22

"eSb9GNFURwVgKuJMpsmf"

Store content in vault request

This request stores the uploaded media in vault 3.

POST http://imagevaultui.local/apiv2/mediacontentservice/storecontentinvault HTTP/1.1
Authorization: Bearer mi3hxynuho7s0j8sf8a0
X-Requested-With: XMLHttpRequest
Content-Type: application/json
Host: imagevaultui.local
Content-Length: 100
Expect: 100-continue

{"uploadFileId":"eSb9GNFURwVgKuJMpsmf","filename":"test.txt","contentType":"text/plain","vaultId":3}

Store content in vault response

Here you will get the details of the media item that was stored. The most important part is the Id of the media item.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 136

{
  "Id": 27216,
  "VaultId": 3,
  "Name": "test.txt",
  "DateAdded": "2016-06-25T10:34:36.0605078+02:00",
  "AddedBy": "iv4sdk"
}

Save media request

To mark the media as ready to use, we call the save method and supply the Id of the media item and the saveOption 4 (MarkAsOrganized) that will indicate that the media item is ready to use.

POST http://imagevaultui.local/apiv2/mediaservice/save HTTP/1.1
Authorization: Bearer mi3hxynuho7s0j8sf8a0
X-Requested-With: XMLHttpRequest
Content-Type: application/json
Host: imagevaultui.local
Content-Length: 45
Expect: 100-continue

{"mediaItems":[{"Id":27216}],"saveOptions":4}

This will complete the upload/organize phase and make the uploaded item available to all users with access to the vault where the item is uploaded in.