---
title: "Create a fetch job"
slug: "create-a-fetch-job"
abstract: "Overview of how to create a fetch job with parameters and examples."
---
# 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:

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

```

## Body parameters

To request the creation of a new fetch job, use a [create fetch job request object](https://doc.sitecore.com/ch/en/developers/cloud-dev/create-a-fetch-job-1523319.html "Create a fetch job") with the following required body parameters:

| Parameter | Type | Description |
| --- | --- | --- |
| `state_description` | String | Description of the current state of the job. This parameter needs to be set but can be empty (`""`). |
| `asset` | Link | [Link](https://doc.sitecore.com/ch/en/developers/cloud-dev/link.html) to the asset entity that receives the files. |
| `files` | Array | Array of [file objects](https://doc.sitecore.com/ch/en/developers/cloud-dev/file.html) 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:

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

```

## Response

A successful fetch job returns the following response.

| Response | Description |
| --- | --- |
| `201 Created` | Provides a location header containing the URL of the newly created resource. |

A complete list of possible responses is available in [response codes](https://doc.sitecore.com/ch/en/developers/cloud-dev/response-codes.html "Response codes").

## Response examples

A fetch job response looks like the following example:

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

```