|API Support||Available since||Last updated||Output|
Uploads one or more files using a multipart request.
You can use /upload PUT to upload files. The main difference is that PUT only lets you upload a single file in the body of the request. And using autoload, you can specify the title, description, document ID and labels as parameters which isn’t possible with POST.
Administrators can upload on behalf of another member using the member parameter.
There are two modes of operation depending on whether the autoload parameter was used.
By default, the files are uploaded into the loading zone. When the autoload parameter is
true, the files are uploaded directly into the target folder of the specified group.
Some limitations are controlled by global properties:
- The maximum upload size is defined by the
- The maximum number of attachments to a comment are defined by the
- The maximum number of workflow notifications is defined by the
Loading zone upload (default)
The loading zone is a temporary container for files on the server before they are loaded into PageSeeder.
There is a separate loading zone for each member on each group. Within a group, a member can have multiple loading zones by specifying a unique uploadid or xlinkid for each one. An xlinkid is used to upload attachments to a draft comment before it is submitted (the xlinkid is the same as the comment ID).
After files have been uploaded, the various load services can be used to modify, unzip them and start loading them into PageSeeder.
Direct upload (autoload)
When autoload parameter is
true , the files are loaded directly into the target group and folder using a default configuration.
You can specify the target location using the url or the folder parameter. If neither is specified, the file is uploaded into the root folder of the group.
Use the overwrite-properties parameter if you want to update the title, description, labels or metadata of the target URI if it exists. This parameter has no effect if overwrite is not set to
You cannot use autoload for attachments to comments, so specifying
autoload=true with an xlinkid parameter returns an error.
Autoload is synchronous only if a single file is uploaded. When multiple files are uploaded, PageSeeder creates a thread and returns a HTTP 202 status code.
|autoload||Whether the upload bypasses the loading zone||no||boolean|
|file-[n]||The nth file to upload as a multipart parameter (required)||yes||string|
|folder-[n]||The folder to upload the nth file to as a multipart parameter (relative to loading zone root)||no||string|
|folder||The folder the files should be uploaded into (relative to the root of the group - used with autoload only, ignored if url is specified)||no||string|
|group||The name of the group the file should be uploaded into||yes||string|
|member||ID or username of a member to upload on behalf of (for admins only)||no||string|
|overwrite||Whether the uploaded file should overwrite an existing file (in loading zone and PageSeeder)||no||boolean|
|overwrite-properties||Whether the uploaded file should overwrite existing URI properties (autoload only)||no||boolean|
|uploadid||An ID to uniquely identify this upload (can be letters, numbers or hyphens up to 100 chars long, overrides xlinkid)||no||string|
|url||A URL pointing to the folder the files should be uploaded into (autoload only)||no||url|
|xlinkid||A comment ID used to build an upload ID (for comment attachments’ loading zone - no autoload).||no||long|
The permission required depends on the target context.
When attaching a file to a comment, the user must be a member of the group. Otherwise, the user must have edit permissions on the target folder (contributor and higher).
Anti-CSRF-Token token is required to use this service.
The response depends on whether the autoload parameter was used and if multiple files were uploaded at once, in which case it starts an asynchronous process.
Loading zone upload (default)
By default, this service returns the details of files that were uploaded:
<upload member="[member ID]" [uploadid="[uploadid]"] max-workflow-notifications="20"> <file name="[filename]" path="[path]" type="file" ... /> ... </upload>
Direct upload (autoload)
true and only one file is uploaded, this service returns the details of the URI created as a result of the upload in a <uri> element:
<upload member="[member ID]" [uploadid="[uploadid]" status="[failed|completed]"] max-workflow-notifications="20"> <message>[explanation or error]<message> <uri id="[uri id]" ... /> </upload>
true and multiple files are uploaded, this service returns the details of the thread created in a <thread> element:
<upload member="[member ID]" [uploadid="[uploadid]"] max-workflow-notifications="20"> <thread id="[thread ID]" ...> [thread XML] <thread> </upload>
|HTTP code||Error condition|
|400||The Content-Type request header is not multipart/form-data|
|400||The parameter group is not specified or does not match an existing group|
|400||The selected destination folder or URL is invalid|
|400||The parameter xlinkid or uploadid is not valid|
|400||The parameter member doesn’t match an existing member ID or username|
|400||Attempting to upload a PSML document to a comment (xlinkid parameter is specified and the filename ends with .psml)|
|400||Maximum number of files has been reached when attaching to a comment (default is 20)|
|409||One of the files already exists and overwrite parameter is set to false|
|413||One of the files exceeds the maximum upload size (default is 100MB)|