---
title: "Task"
url: "https://dev.4hse.com/api/task"
---

# Task

A **Task** is an operation the platform runs in the background instead of during the request, because it is too long to complete inline — for example synchronising the people of a project from a CSV file.

Each task records the `handler` that performs the work, the `user_id` who started it, the `request` it was given and the `response` it produced.

The `status` follows this lifecycle:

-   `TODO`: queued, not started yet
-   `PENDING`: waiting on an external condition
-   `PROCESSING`: running
-   `DONE`: completed successfully — the outcome is in `response`
-   `FAILED`: stopped with an error — the reason is in `response`

Use this API to:

-   Follow an operation you started, by polling its status
-   Read the result of a completed task
-   Find the tasks started by a user (filter by `user_id`)

Version

2.0.0

OpenAPI version

3.0.0

## Authentication

[Section titled “ Authentication ”](#authentication)

### OAuth2

[Section titled “OAuth2 ”](#oauth2)

**Security scheme type:** oauth2

**Flow type:** password

**Token URL:** [https://auth.4hse.com/realms/4hse/protocol/openid-connect/token](https://auth.4hse.com/realms/4hse/protocol/openid-connect/token)

### AccessToken

[Section titled “AccessToken ”](#accesstoken)

**Security scheme type:** apiKey

**Query parameter name:** access-token

## Operations

[Section titled “Operations”](#operations)

### index

[Section titled “index”](#operation-indexTask-post)

POST

/v2/task/index

-   

Returns a paginated and filterable list of tasks. Use POST to allow complex filters via JSON payload.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/task/#oauth2)**
-   **[AccessToken](/api/task/#accesstoken)**

#### Request Body

[Section titled “Request Body ”](#request-body)

Parameters for searching tasks

Select media typeapplication/json

object

**filter**

object

**task\_id**

The unique identifier for the task.

string format: uuid

**handler**

The name of the handler assigned to the task.

string

**user\_id**

The unique identifier for the user associated with the task.

string

**entity\_id**

The unique identifier for the entity associated with the task (optional).

string

nullable

**status**

The current status of the task (e.g., pending, completed, etc.).

string

**request**

The JSON request data related to the task.

string format: json

nullable

**response**

The JSON response data related to the task.

string format: json

nullable

**created\_at**

The timestamp when the task was created.

string format: date

**updated\_at**

The timestamp when the task was last updated.

string format: date

**per-page**

integer

default: 100 \>= 1

**page**

integer

default: 1 \>= 1

**sort**

Field to sort by. Prefix with minus for descending order (e.g. -created\_at).

string

Allowed values: status created\_at updated\_at

##### Example

```
{  "filter": {    "handler": "ImportHandler",    "status": "pending"  },  "per-page": 10,  "page": 1,  "sort": "created_at"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of tasks

Select media typeapplication/json

Array<object>

object

**task\_id**

The unique identifier for the task.

string format: uuid

**handler**

The name of the handler assigned to the task.

string

**user\_id**

The unique identifier for the user associated with the task.

string

**entity\_id**

The unique identifier for the entity associated with the task (optional).

string

nullable

**status**

The current status of the task (e.g., pending, completed, etc.).

string

**request**

The JSON request data related to the task.

string format: json

nullable

**response**

The JSON response data related to the task.

string format: json

nullable

**created\_at**

The timestamp when the task was created.

string format: date

**updated\_at**

The timestamp when the task was last updated.

string format: date

##### Example

```
{  "task_id": "task-1",  "handler": "ImportHandler",  "user_id": "user-1",  "status": "pending",  "created_at": "2024-01-01",  "updated_at": "2024-01-02"}
```

#### Headers

[Section titled “Headers ”](#headers)

**X-Pagination-Current-Page**

integer

Current page

**X-Pagination-Page-Count**

integer

Total number of pages

**X-Pagination-Per-Page**

integer

Number of items per page

**X-Pagination-Total-Count**

integer

Total number of items

### create

[Section titled “create”](#operation-createTask-post)

POST

/v2/task/create

-   

Create a new task by providing the required details.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/task/#oauth2)**
-   **[AccessToken](/api/task/#accesstoken)**

#### Request Body required

[Section titled “Request Body required ”](#request-body)

Task object to be created

Select media typeapplication/json

object

**task\_id**

The unique identifier for the task.

string format: uuid

**handler**

The name of the handler assigned to the task.

string

**user\_id**

The unique identifier for the user associated with the task.

string

**entity\_id**

The unique identifier for the entity associated with the task (optional).

string

nullable

**status**

The current status of the task (e.g., pending, completed, etc.).

string

**request**

The JSON request data related to the task.

string format: json

nullable

**response**

The JSON response data related to the task.

string format: json

nullable

**created\_at**

The timestamp when the task was created.

string format: date

**updated\_at**

The timestamp when the task was last updated.

string format: date

##### Example

```
{  "handler": "ExportHandler",  "user_id": "user-2",  "status": "pending"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 201

[Section titled “201 ”](#201)

Task created successfully

Select media typeapplication/json

object

**task\_id**

The unique identifier for the task.

string format: uuid

**handler**

The name of the handler assigned to the task.

string

**user\_id**

The unique identifier for the user associated with the task.

string

**entity\_id**

The unique identifier for the entity associated with the task (optional).

string

nullable

**status**

The current status of the task (e.g., pending, completed, etc.).

string

**request**

The JSON request data related to the task.

string format: json

nullable

**response**

The JSON response data related to the task.

string format: json

nullable

**created\_at**

The timestamp when the task was created.

string format: date

**updated\_at**

The timestamp when the task was last updated.

string format: date

##### Example

```
{  "task_id": "task-2",  "handler": "ExportHandler",  "user_id": "user-2",  "status": "pending"}
```

### view

[Section titled “view”](#operation-viewTask-get)

GET

/v2/task/view/{id}

-   

Retrieve a task by its unique ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/task/#oauth2)**
-   **[AccessToken](/api/task/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

ID of the task to retrieve

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Task found

Select media typeapplication/json

object

**task\_id**

The unique identifier for the task.

string format: uuid

**handler**

The name of the handler assigned to the task.

string

**user\_id**

The unique identifier for the user associated with the task.

string

**entity\_id**

The unique identifier for the entity associated with the task (optional).

string

nullable

**status**

The current status of the task (e.g., pending, completed, etc.).

string

**request**

The JSON request data related to the task.

string format: json

nullable

**response**

The JSON response data related to the task.

string format: json

nullable

**created\_at**

The timestamp when the task was created.

string format: date

**updated\_at**

The timestamp when the task was last updated.

string format: date

##### Example

```
{  "task_id": "task-1",  "handler": "ImportHandler",  "user_id": "user-1",  "status": "pending",  "created_at": "2024-01-01",  "updated_at": "2024-01-02"}
```

##### 404

[Section titled “404 ”](#404)

Task not found

### delete

[Section titled “delete”](#operation-deleteTask-delete)

DELETE

/v2/task/delete/{id}

-   

Delete a task by its unique ID. If force=true, all related entities will also be deleted.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/task/#oauth2)**
-   **[AccessToken](/api/task/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

ID of the task to delete

#### Query Parameters

[Section titled “Query Parameters ”](#query-parameters)

**force**

boolean

Force the deletion of the entity and all related entities

#### Responses

[Section titled “ Responses ”](#responses)

##### 204

[Section titled “204 ”](#204)

Task deleted successfully

##### 400

[Section titled “400 ”](#400)

If force=false, the operation is interrupted and the list of connected entities that will be deleted in case of confirmation (force=true) is returned

### update

[Section titled “update”](#operation-updateTask-put)

PUT

/v2/task/update/{id}

-   

Update an existing task by its unique ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/task/#oauth2)**
-   **[AccessToken](/api/task/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

ID of the task to update

#### Request Body required

[Section titled “Request Body required ”](#request-body)

Task object with updated data

Select media typeapplication/json

object

**task\_id**

The unique identifier for the task.

string format: uuid

**handler**

The name of the handler assigned to the task.

string

**user\_id**

The unique identifier for the user associated with the task.

string

**entity\_id**

The unique identifier for the entity associated with the task (optional).

string

nullable

**status**

The current status of the task (e.g., pending, completed, etc.).

string

**request**

The JSON request data related to the task.

string format: json

nullable

**response**

The JSON response data related to the task.

string format: json

nullable

**created\_at**

The timestamp when the task was created.

string format: date

**updated\_at**

The timestamp when the task was last updated.

string format: date

##### Example

```
{  "status": "completed"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Task updated successfully

Select media typeapplication/json

object

**task\_id**

The unique identifier for the task.

string format: uuid

**handler**

The name of the handler assigned to the task.

string

**user\_id**

The unique identifier for the user associated with the task.

string

**entity\_id**

The unique identifier for the entity associated with the task (optional).

string

nullable

**status**

The current status of the task (e.g., pending, completed, etc.).

string

**request**

The JSON request data related to the task.

string format: json

nullable

**response**

The JSON response data related to the task.

string format: json

nullable

**created\_at**

The timestamp when the task was created.

string format: date

**updated\_at**

The timestamp when the task was last updated.

string format: date

##### Example

```
{  "task_id": "task-1",  "status": "completed"}
```

##### 404

[Section titled “404 ”](#404)

Task not found

This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.