Page tree
Skip to end of metadata
Go to start of metadata

Upload one or more photos to the server.

API version



An upload is done by posting one or more files to the upload URL as content-type multipart/form-data.

It is possible to upload multiple files with one request. It is also possible to attach metadata information as a JSON-Object that will be written to the file once it has been uploaded to the server.


  • Make sure that PicApport is not running in demo-mode (set server.demomode=false)

  • Make sure the the user you are using for the WebApi context has the permission to upload photos.
    (Test with PicApport if you are not sure)

  • Make sure that PicApports upload function is configured properly (upload.* parameter on PicApport-Server Guide)

How it works

Check the uploadPhotos() function in sourcecode(select view source) of PicApport WebApi-frontend on

var formData = new FormData();
var photos = document.querySelector("input[type='file'][multiple]");
formData.append('metadata', JSON.stringify({"title": "Optional title",
										    "description": "Optional description",
											"rating": 5,
											"tags": ["tag1", "tag2"],									   
											"persons": ["person 1", "person 2"],
for (var i = 0; i < photos.files.length; i++) {
    formData.append('photos', photos.files[i]);
fetch(createUrl("upload", ["apisid"]), {
				method: 'POST',
				body: formData
				.then(response => response.json())
   	            .then(json => console.log("Upload result: ", json))
	            .catch(error => console.log("UploadError: " + error)); 

Metadata is applied to all photos until they are changed. So the following is possible:

var formData = new FormData();
formData.append('metadata', JSON.stringify(metadata1
formData.append('photos', photoFile1....
formData.append('metadata', JSON.stringify(metadata2
formData.append('photos', photoFile2....
formData.append('photos', photoFile3....
POST formdata using fetch.....

In the example above photoFile1 gets metadata1 and photoFile2+photoFile3 get metadata2

Version Note: Since version 8.3 it is also possible to have e unique photoID field in the metadata-JSON of the request.

Version Note: Since version 9.1.04 it is also possible to have e unique doSyncCheck field in the metadata-JSON of the request.

  • doSyncCheck  optional Parameter. (default = true)
    If set to false, the check if the photo has already been transferred is omitted.
    Important: Regardless of the setting of this parameter the photo will still not be accepted if a photo with this ID exists in the database.


apisidstring7.4yes Based on the setting of webapi.default.uid in you may provide one of the following values
  • Session-ID returned from createWebApiSession

  • If you do not provide apisid and configuration parameter webapi.default.uid is set to a valid userid (with same password)
    a WebApi-Session will be created implicitly for the defined user.

  • If an existing userID is provided (with password set to same value as userID ) a WebApi-Session will be created implicitly
    for the defined userID.


mime typeapplication/json
contentInformation about the upload result
http status codes
  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 500 Internal Server Error
  • 501 Not implemented




apisidstring7.4Session-ID returned from createWebApiSession

Each array element has the following members



fileNamestring7.4The filename used on the PicApport Server
contentTypestring7.4image/jpeg for .jpg Files

The size of the file in bytes

photoIDstring7.4The unique PicApport photoID created after the upload.
This ID may be used to access the photo.
  • OK
    Photo was uploaded successfully
  • Server Error: File too big.
    File was too big (see configuration parameter upload.max.filesize.mb)
  • Server Error: Invalid content type
    currently only image/jpeg is supported
  • No labels