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

OAuth2

Security scheme type: oauth2

Flow type: password

Token URL: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token

AccessToken

Security scheme type: apiKey

Query parameter name: access-token

Operations

index

POST

/v2/task/index

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

Authorizations

OAuth2
AccessToken

Request Body

Parameters for searching tasks

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

200

List of tasks

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

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

POST

/v2/task/create

Create a new task by providing the required details.

Authorizations

OAuth2
AccessToken

Request Body^required

Task object to be created

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

201

Task created successfully

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

GET

/v2/task/view/{id}

Retrieve a task by its unique ID.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

ID of the task to retrieve

Responses

200

Task found

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

Task not found

delete

DELETE

/v2/task/delete/{id}

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

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

ID of the task to delete

Query Parameters

force

boolean

Force the deletion of the entity and all related entities

Responses

204

Task deleted successfully

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

PUT

/v2/task/update/{id}

Update an existing task by its unique ID.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

ID of the task to update

Request Body^required

Task object with updated data

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

200

Task updated successfully

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

Task not found

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Task

Authentication

OAuth2

AccessToken

Operations

index

Authorizations

Request Body

Example

Responses

200

Example

Headers

create

Authorizations

Request Body required

Example

Responses

201

Example

view

Authorizations

Path Parameters

Responses

200

Example

404

delete

Authorizations

Path Parameters

Query Parameters

Responses

204

400

update

Authorizations

Path Parameters

Request Body required

Example

Responses

200

Example

404

Request Body^required

Request Body^required