Table of Contents
Uploading assets using the API (Feature Release 4)
17. June 2025
Table of Contents
Assets can be added to archives by copying or moving them from other archives or uploading new files.
The FotoWeb API supports uploading one or more files in one single HTTP request. Furthermore, it is possible to create new folders and folder hierarchies and apply metadata to files in the same request.
Syntax
Files are uploaded by making a POST request to the URL of the collection to upload to. When uploading to a new folder (which is created by the upload request), then the hierarchy of new folders is added to the end of the URL as follows:
POST folder_url/folder1/folder2/.../
where
-
folder_urlis the URL of the collection to upload to -
folder1,folder2, ... are optional names of new folders to be created
New folders can only be created if the canCreateFolders flag is set on the upload location and the archive does not have a custom ingestion folder. For more information, see ingestion.
Note: If the folder_url is taken from the JSON representation of a collection, then it must be the URL given in the href attribute, not the data attribute.
Request Body
Upload uses HTTP Multipart requests. This means that upload is easy to implement on the client side when using an HTTP client library with built-in support for file upload. If the HTTP request has to be crafted manually, see RFC1341 for more information.
Here is an example of a complete upload request for one file:
POST /fotoweb/archives/5000-Wirefeed/Incoming/ Accept: application/vnd.fotoware.upload-result+json Content-Type: multipart/form-data; boundary=WUG7zDvyA3hVq16Q authentication headers --WUG7zDvyA3hVq16Q Content-Disposition: form-data; name="Filedata"; filename="image.jpg" Content-Type: image/jpeg binary image data --WUG7zDvyA3hVq16Q
The boundary string can be chosen freely by the client. It should be random and long enough to minimize the chance that it occurs in the files being uploaded.
The filename attribute of each part specifies the name that the file will have in FotoWeb. It does not matter what the file is called on the local disk before uploading.
The content type of each part is not used by FotoWeb, but it should be the correct MIME type of the file, such as image/jpeg.
The blank lines are all required, and line breaks must be in CRLF format.
Response
In the response to the request, FotoWeb returns information in JSON format about the uploaded assets. If the upload request was successful, then the response status is 201 Created, and the Location header contains the URL of the first uploaded image.
201 Created Location: https://fotoweb.acme.com/fotoweb/archives/5000-Wirefeed/Incoming/image.jpg Content-Type: application/vnd.fotoware.upload-result+json
If more than one files was uploaded, then the Location header only contains the URL of one asset that was created. Information about all assets can be obtained by parsing the JSON in the response body, which has the following format:
01 |
{ |
02 |
uploadedFiles: [ |
03 |
{ |
04 |
asset: { href: /fotoweb/archives/5000-Wirefeed/Incoming/image.jpg, ... }, |
05 |
originalFilename; "image.jpg" |
06 |
}, |
07 |
{...}, |
08 |
... |
09 |
] |
10 |
} |
The uploadedFiles attribute is an array with one entry per file/asset. Each element is an object with the following attributes:
originalFilename |
string | The filename given in the upload request |
asset |
object (Asset) | All information about the asset that was created. |
Note that information about the asset is not available when uploading to an archive with a custom ingestion folder. This is because FotoWeb does not know where the file will end up. For example, the ingestion folder might be the input folder of a ColorFactory channel, which processes and potentially moves the file. As a result of the processing, zero or more files may eventually end up in FotoWeb archives.
Applying Metadata
Metadata can be applied to assets during upload. This ensures strong metadata consistency in FotoWeb archives. If a client uploaded files and applied metadata later in a separate request, then these assets might be without metadata, without consistent metadata, or without required metadata fields for a short period after the upload. Applying metadata during upload ensures that all assets in the FotoWeb systems always have fully consistent metadata.
Metadata can be applied to each file in an upload request. This is done by adding a new part to the request body for each file to which metadata shall be applied. This metadata part looks has the following XML syntax:
1 |
Content-Disposition: form-data; name="metadata:image.jpg" |
2 |
3 |
<?xml version='1.0' encoding='utf-8'?>
|
4 |
<Text> |
5 |
<Field Id="IPTC2:5">Roadrunner</Field>
|
6 |
<Field Id="IPTC2:80">Wyle E. Coyote</Field>
|
7 |
... |
8 |
</Text> |
Note that the string in the first line is the boundary string for the multi-part format, which was described above.
The name attribute of the Content-Disposition header must be "metadata: filename" where filename must be equal to the name attribute of the Content-Disposition header of the part that contains the binary data of the file to which the metadata is being applied.
Each Field element in the XML specifies a metadata action on the file. The general syntax of a metadata action is:
<Field Action="add|append|prepend|erase" Id="IPTC2:fieldnum">value</Field>
where fieldnum is the number of the metadata field (see here for a list of predefined metadata fields and here for information about defining custom fields) and Action can be one of the following:
add |
Set the field to the given value. If the field already has a value, and the field is a bag field, then the value is added to the array of values of the field. This action is the default if no action is given explicitly. The add action requires non-empty value field. If an empty value field is present, then the request does nothing for that metadata field, i.e. the metadata is preserved for that field. |
append |
Append the given value to the existing value of the field. If the field does not have a value, then this action is equivalent to If the field is a bag field, then the given value is appended to the first value of the existing array of values of the field. |
| prepend |
Prepend the given value to the existing value of the field. If the field does not have a value, then this action is equivalent to If the field is a bag field, then the given value is prepended to the first value of the existing array of values of the field. |
erase |
Remove the given field from the metadata. If the field is a bag field, it erases all its values. |
Example: Applying Metadata to Regular Fields
The following metadata patch syntax:
1 |
<Field Id="IPTC2:500">V1</Field>
|
2 |
<Field Action="erase" Id="IPTC2:501">V2</Field>
|
3 |
<Field Action="append" Id="IPTC2:502">V3</Field>
|
4 |
<Field Action="prepend" Id="IPTC2:503">V4</Field>
|
modifies the following existing metadata as follows:
| Field | Existing value | Final value |
| 500 | E1 | V1 |
| 501 | E2 | (undefined) |
| 502 | E3 | E3V3 |
| 503 | E4 | V4E4 |
Example: Applying Metadata to a bag field
The following metadata patch syntax:
1 |
<Field Action="erase" Id="IPTC2:25"></Field>
|
2 |
<Field Id="IPTC2:25">food</Field>
|
3 |
<Field Id="IPTC2:25">chicken</Field>
|
4 |
<Field Id="IPTC2:80">Wyle E. Coyote</Field>
|
Modifies the following existing metadata as follows:
| Field | Existing value | Final value |
| 25 | foo, bar | food, chicken |
| 80 | John Smith | John Smith, Wyle E. Coyote |
Note that the erase action applied to field 25 first clears the bag field before adding new values. This replaces all values in the bag field with new values. Without the erase action, as shown here for field 80, the new values are added to the existing ones in the bag field.
Full example
The following is an example of a complete upload request with metadata:
POST /fotoweb/archives/5000-Wirefeed/Incoming/ Accept: application/vnd.fotoware.upload-result+json Content-Type: multipart/form-data; boundary=WUG7zDvyA3hVq16Q authentication headers --WUG7zDvyA3hVq16Q Content-Disposition: form-data; name="Filedata"; filename="image.jpg" Content-Type: image/jpeg binary image data --WUG7zDvyA3hVq16Q Content-Disposition: form-data; name="metadata:image.jpg" <?xml version='1.0' encoding='utf-8'?> <Text> <Field Action="erase" Id="IPTC2:25"></Field> <Field Id="IPTC2:25">food</Field> <Field Id="IPTC2:25">chicken</Field> </Text> --WUG7zDvyA3hVq16Q
Which collections support uploading?
Files can only be uploaded to archives. Furthermore, files can only be uploaded to certain locations in archives, such as physical folders or (if the archive has a custom ingestion folder) the root of the archive itself. The upload destination list API can be used to discover possible upload locations. For more information, see ingestion.
Uploading to the Upload Area
It is also possible to upload files to the upload area using the API. If the upload area is available as an upload destination, then the upload destination list will include an entry for it. Note that every user has a separate upload area, so uploading to the upload area is only meaningful if the client is authenticated as a specific user.
Required permissions
Upload requires authentication.
If server-to-server authentication is used, then the client can upload files anywhere upload is supported.
If the client is authenticated as a specific user, then that user must have upload permission on the archive.
The upload destination list filters by permissions, so the client does not explicitly need to check permissions.
Upload example using cURL
The following command uploads two files to an archive with a custom ingestion folder:
curl --header "FWAPIToken: 12345" \ -F "image=@/Users/<User Name>/Desktop/file1.JPG" \ -F "image=@/Users/<User Name>/Desktop/file2.pdf" \ http://beta.fotoware.com/fotoweb/archives/5004-Uploads/
Remarks
The maximum file size of uploads is limited by the maximum size of requests to FotoWeb. This is currently 2 GB when using IIS and 4 GB when using Apache. Note that when uploading multiple files in one request, the limit applies to the total size of the file, including headers and metadata. It is therefore recommended to upload files in one request per file if files may be large.