Create a fetch job

Using the REST API, you can create fetch jobs. When you create a fetch job, referenced files are downloaded and added to the file history of the referenced M.Asset resource. The last file in the request list becomes the new master file.

When a fetch job targets an asset that already has an existing file attached to it:

  • The file already associated with the asset moves to the file history. By default, the file history displays in a pane beneath the preview thumbnail.
  • The newly uploaded file becomes the master file, which displays in the preview.
  • If a fetch job has more than one file in the array of files, the last file provided becomes the master file. The other files become alternative files.

To create a fetch job, you need to send a request to the following endpoint:

POST https://<hostname>/api/fetchjobs

Body parameters

To request the creation of a new fetch job, use a create fetch job request object with the following required body parameters:

state_descriptionStringDescription of the current state of the job. This parameter needs to be set but can be empty ("").
assetLinkLink to the asset entity that receives the files.
filesArrayArray of file objects that describes where to retrieve the files to add to the asset. The last file in the list of the request becomes the new master file.

Body examples

You can use the following example code in the body of the request:

  "state_description": "",
  "asset": {
    "href": "https://<hostname>/api/entities/23"
  "files": [
      "type": "Web",
      "href": "https://www.gstatic.com/webp/gallery/5.jpg"


A successful fetch job returns the following response.

201 CreatedProvides a location header containing the URL of the newly created resource.

A complete list of possible responses is available in response codes.

Response examples

A fetch job response looks like the following example:

HTTP/1.1 201 Created
Location: /api/fetchjobs/6448

Can we improve this article ? Provide feedback