HTTP Upload

Binary files can be uploaded by POSTing files in multipart/form-data format to the upload URL:

curl -i -HX-User:myuser -HX-Password:mypasswd -F 'file=@myfile.txt;type=text/plain' http://localhost:8082/structr/upload

Server Response

The HTTP header of the response will look like this:

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Date: Wed, 02 Mar 2016 09:10:53 GMT
Set-Cookie: JSESSIONID=1ircxf0n7lfr81jlwx92h6s5jx;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: text/html; charset=UTF-8
Vary: Accept-Encoding, User-Agent
Content-Length: 32
Server: Jetty(9.2.9.v20150224)

The response body contains the UUID of the File node created in Structr:


Multiple Files

This works also with multiple files:

curl -i -HX-User:myuser -HX-Password:mypasswd -F 'file=@myfile.text;type=text/plain' -F 'file=@another-file.pdf;type=application/pdf' http://localhost:8082/structr/upload

The return body consists of the concatenated UUIDs of the File nodes created in Structr.


Passing additional parameters

There are a couple of predefined parameters to control the behaviour of the upload endpoint:

redirectOnSuccess [URI]: Define a page URI to redirect after successful upload
appendUuidOnRedirect [true|false]: Append the UUID of the uploaded file to the redirect URI
New since 2.1.4: uploadFolderPath: Structr will create the missing folders before uploading to the folder with the given folder path

You can also pass additional parameters to set attributes of the File node created in Structr. For instance, this can be used to upload the file to an existing Folder:

curl -i -HX-User:myuser -HX-Password:mypasswd -F 'parentId=9f06ab14bb8e4e6a9e50d0cbb8de1937' -F 'file=@myfile.text;type=text/plain' http://localhost:8082/structr/upload

The value for parentIdis the UUID of the Folder node in Structr the file will be uploaded to. Please note that the additional parameters have to be defined before the file they belong to.


The order of parameters defines which additional attributes are valid at any point. A parameter is valid until it is explicitly overwritten. This way multiple files can be uploaded in one request with all files being of different types (achievable by adding an input file with name=“type” and value=“FileTypeXYZ”) between the different files.

About this article
Last change 2019-07-11