# Tasks API

This set of endpoints allows us to interact with tasks that have been created in the Nexus Repository. You will need appropriate privileges to view, create, update, or delete tasks.

See the [Tasks](https://help.sonatype.com/en/tasks.html "Tasks") documentation.

## List Tasks

This endpoint iterate through a listing of all the existing tasks.

```
GET /service/rest/v1/tasks
```

```
curl 'http://localhost:8081/service/rest/v1/tasks' \
  -u admin:admin123 \
  -H 'accept: application/json'
```

Include the type of tasks filter the results.

```
curl 'http://localhost:8081/service/rest/v1/tasks?type=assetBlob.cleanup' \
  -u admin:admin123 \
  -H 'accept: application/json'
```

### [Example Response](https://help.sonatype.com/en/tasks-api.html#example-response-162184_body)

```
{
  "items" : [ {
    "id" : "3f0173a8-c379-44c3-8ba3-2f0d0290bbfa",
    "name" : "Rebuild all browse trees",
    "type" : "create.browse.nodes",
    "message" : null,
    "currentState" : "WAITING",
    "lastRunResult" : null,
    "nextRun" : null,
    "lastRun" : null
  }, {
    "id" : "0261aed9-9f29-447b-8794-f21693b1f9ac",
    "name" : "Hello World",
    "type" : "script",
    "message" : null,
    "currentState" : "WAITING",
    "lastRunResult" : null,
    "nextRun" : null,
    "lastRun" : null
  } ],
  "continuationToken" : null
}
```

## Get Task by Identifier

This endpoint retrieves the details on an individual task.

```
GET /service/rest/v1/tasks/{id}
```

```
curl 'http://localhost:8081/service/rest/v1/tasks/0261aed9-9f29-447b-8794-f21693b1f9ac' \
  -u admin:admin123 \
  -H 'accept: application/json'
```

### [Example Response](https://help.sonatype.com/en/tasks-api.html#example-response-162184-1_body)

```
{
  "id" : "0261aed9-9f29-447b-8794-f21693b1f9ac",
  "name" : "Hello World",
  "type" : "script",
  "message" : null,
  "currentState" : "WAITING",
  "lastRunResult" : null,
  "nextRun" : null,
  "lastRun" : null
}
```

## Run Task

This endpoint runs an individual task.

```
POST /service/rest/v1/tasks/{id}/run
```

```
curl -u admin:admin123 -X POST 'http://localhost:8081/service/rest/v1/tasks/0261aed9-9f29-447b-8794-f21693b1f9ac/run'
```

#### Example Response

```
HTTP/1.1 204 No Content
Date: Mon, 22 Jan 2018 22:19:47 GMT
...
```

## Stop Task

```
POST /service/rest/v1/tasks/{id}/stop
```

This endpoint allows us to stop an individual task. This is the equivalent of cancelling a task in the repository manager UI. Note that not all tasks will respond to a cancellation request.

For example to stop the "Hello World" task:

```
curl -u admin:admin123 -X POST 'http://localhost:8081/service/rest/v1/tasks/0261aed9-9f29-447b-8794-f21693b1f9ac/stop'
```

In this example the "Hello World" task was not running when the stop request was made. We will get a 409 response code that signifies that the requested task was not currently running:

**Example Response**

```
HTTP/1.1 409 Conflict
Content-Length: 0
Date: Mon, 22 Jan 2018 22:22:33 GMT
...
```

## Nexus Repository Pro Endpoints

### Task Frequency

The following are examples of the JSON object used to set the task frequency property.

```
"frequency": {
  "schedule": "once",
  "startDate": 0,
  "timeZoneOffset": "+3",
  "recurringDays": [
    0
  ],
  "cronExpression": "string"
}
```

- #### schedule

The frequency of how often the task should run.

```
Manual, Once, Hourly, Daily, Weekly, Monthly, Advanced
```

- #### startDate

Time to start the run of the task using the unix timestamp in milliseconds. Does not apply for the manual schedule.

See [Epoch Unix Converter](https://www.epochconverter.com/)

- #### timeZoneOffset

Property defaults to GMT (0) unless including an offset for the server timezone. Example:

```
  -05:00
```

- #### recurringDays

Array with the number of the days the task must run.

For weekly schedule allowed values, 1 to 7.

For monthly schedule allowed values, 1 to 31.

- #### cronExpression

A cron expression for the frequency when the schedule is set to Advanced

See the [Tasks](https://help.sonatype.com/en/tasks.html "Tasks") documentation.

### Create Task

```
POST /service/rest/v1/tasks/
```

The Create endpoint allows you to create a task from the API rather than from the user interface. Below is an example for creating a Cleanup Tags task.

```
curl -X 'POST' \
  'https://localhost:8081/service/rest/v1/tasks' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'NX-ANTI-CSRF-TOKEN: 1.1.1.1' \
  -H 'X-Nexus-UI: true' \
  -d '{
  "type": "tags.cleanup",
  "name": "Test Tags Cleanup",
  "enabled": true,
  "alertEmail": "abc@123.com",
  "notificationCondition": "FAILURE",
  "frequency": {
    "schedule": "once",
    "startDate": 0,
    "timeZoneOffset": "+3",
    "recurringDays": [
      0
    ],
    "cronExpression": "string"
  }
}'
```

### Update Task

The update endpoint allows you to update an existing task outside of the user interface. You must know the task's ID to update the task. If you do not know a task's ID, use the [Get Task endpoint](https://help.sonatype.com/en/tasks-api.html#get-task-by-identifier "Get Task by Identifier") first to find the task and its associated ID.

```
PUT /service/rest/v1/tasks/{taskId}
```

Below is an example using this endpoint to update the schedule for a Tag Cleanup task.

```
curl -X 'PUT' \
  'https://localhost:8081/service/rest/v1/tasks/{taskID}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'NX-ANTI-CSRF-TOKEN: 1.1.1.1' \
  -H 'X-Nexus-UI: true' \
  -d '{
  "name": "Test Tags Cleanup",
  "enabled": false,
  "alertEmail": "abc@123.com",
  "notificationCondition": "FAILURE",
  "frequency": {
    "schedule": "daily",
    "startDate": 0,
    "timeZoneOffset": "+3",
    "recurringDays": [
      0
    ],
    "cronExpression": "0 0 12 * * ?"
  }
}'
```

### Delete Task

```
DELETE /service/rest/v1/tasks/{id}
```

The Delete Task endpoint allows you to delete an existing task by task ID. If you do not know a task's ID, use the [Get Task endpoint](https://help.sonatype.com/en/tasks-api.html#get-task-by-identifier "Get Task by Identifier") first to find the task and its associated ID.

Below is an example of deleting a Tag Cleanup task using its ID.

```
curl -X 'DELETE' 'https://localhost:8081/service/rest/v1/tasks/{taskID}' \
  -H 'accept: application/json'
```

### Get Task Templates

A list of task templates contains task properties for any task type. Use a template as a source when constructing requests to create or update tasks.

```
GET /service/rest/v1/tasks/templates
```

Below is an example for retrieving all of the task templates in a given deployment:

```
curl 'https://localhost:8081/service/rest/v1/tasks/templates' \
  -H 'accept: application/json'
```

Passing in the typeID retrieves a specific task template for that type.

```
GET /service/rest/v1/tasks/templates/{typeId}
```

## Search results

No results found.