/api/v1/task

Use this endpoint to store & retrieve tasks. A task is a configuration to run a task module with pre-configured parameters. The tasks are executed in the background. Tasks can be scheduled to run periodically.

Tasks are user specific. Like exports, tasks are run under as the user who created the task. When listing tasks, only the creating user can see his tasks.

Every task operation requires the system right system.task (a system.root user is also accepted). An unauthenticated request returns 401 with code UserRequired; an authenticated user lacking system.task (and not system.root) returns 403 with code SystemRightRequired. The id-addressed operations GET /task/{taskId}/log, POST /task/{taskId}/cancel and DELETE /task/{taskId} load the task by id and then reject a caller who is neither the task's owner nor a system.root user with 403 code InsufficientRights. The list and GET /task/{taskId} instead filter by the session user, so another user's tasks are simply not returned (an unknown id yields 404).

GET /task

get

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

offsetnumber · int64Optional

Request the given offset of the log.

limitnumber · int64Optional

Request using the given limit. Default is 100.

Responses

200

Retrieve a list of tasks

application/json

limitnumber · int64Optional

The limit of the request.

offsetnumber · int64Optional

The offset of the request.

countnumber · int64Optional

The total count of the tasks of the session user.

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system.task system right (and is not system.root). Raised with code SystemRightRequired (parameters.rights lists the rights that would have satisfied the check).

application/json

{
  "limit": 1,
  "offset": 1,
  "count": 1,
  "objects": [
    {
      "task": {
        "_id": 1,
        "_version": 2,
        "task_module": "sleep",
        "description": "henk is super",
        "task_params": {
          "runtime": 5
        },
        "task_timeout_sec": 100,
        "next_run_at": "2026-05-30T12:00:10Z",
        "status": "new"
      },
      "_user": {
        "_generated_displayname": "root"
      }
    }
  ]
}

POST /task

post

Create a new task.

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

confirmstring · enumOptional

Some task modules answer an unconfirmed save with 202 and a confirmation dialog instead of creating the task (currently consolidate_objects: the preview reports how many records reference the sources and how many of those the saving user is allowed to re-link). Repeat the request with confirm=yes (the confirm key/value of the dialog's button) to create the task.

Possible values:

Body

_basetypestring · enumOptionalPossible values:

created_atstring · datetimeOptional

UTC time of when the task was created.

updated_atstring · datetimeOptional

UTC time of when the task was updated.

Responses

200

Created a new task.

No content

202

The task module asks for a confirmation instead of creating the task: tasks carries title, localized message, machine-readable data and buttons; the button's name/value pair is repeated as a query parameter (confirm=yes) to confirm. consolidate_objects also answers a target-less unconfirmed save with this preview (data: references, relink, denied, capped) — such a probe can never create a task, a confirmed save requires a valid target.

400

The request could not be processed. The code field of the response identifies the specific validation failure.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system.task system right (and is not system.root). Raised with code SystemRightRequired (parameters.rights lists the rights that would have satisfied the check).

application/json

No content

PUT /task

put

Create a new task.

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

confirmstring · enumOptional

Some task modules answer an unconfirmed save with 202 and a confirmation dialog instead of creating the task (currently consolidate_objects: the preview reports how many records reference the sources and how many of those the saving user is allowed to re-link). Repeat the request with confirm=yes (the confirm key/value of the dialog's button) to create the task.

Possible values:

Body

_basetypestring · enumOptionalPossible values:

created_atstring · datetimeOptional

UTC time of when the task was created.

updated_atstring · datetimeOptional

UTC time of when the task was updated.

Responses

200

Created a new task.

No content

202

The task module asks for a confirmation instead of creating the task: tasks carries title, localized message, machine-readable data and buttons; the button's name/value pair is repeated as a query parameter (confirm=yes) to confirm. consolidate_objects also answers a target-less unconfirmed save with this preview (data: references, relink, denied, capped) — such a probe can never create a task, a confirmed save requires a valid target.

400

The request could not be processed. The code field of the response identifies the specific validation failure.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system.task system right (and is not system.root). Raised with code SystemRightRequired (parameters.rights lists the rights that would have satisfied the check).

application/json

No content

GET /task/{taskId}/log

get

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

taskIdnumber · int64Required

The ID of the task.

Query parameters

offsetnumber · int64Optional

Request the given offset of the log.

limitnumber · int64Optional

Request using the given limit. Default is 100.

Responses

200

Task runners can write log entries. This endpoint can be used to retrieve them.

application/json

idxnumber · intOptional

Index of the log entry, starts at 0.

timestampstring · datetimeOptional

UTC time of the entry.

levelstring · enumOptional

Severity of the log entry.

Possible values:

msgstringOptional

Message of the log entry.

status_percentnumber · int64Optional

The current status in percent, can be null. If set (per task module), the task runner updates the status_percent of the task to the latest data.

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user is neither the task's creator nor a system.root user. Tasks are user-specific; only the user who created a task (or a system.root user) can access it. A user without the system.task system right also receives a 403.

application/json

404

No task with this id exists. The id was not loadable. Raised with code ObjectNotFound (parameters.object carries a task <id> token, e.g. task 7).

application/json

[
  {
    "idx": 1,
    "timestamp": "text",
    "level": "debug",
    "msg": "text",
    "status_percent": 1
  }
]

POST /task/{taskId}/cancel

post

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

taskIdnumber · int64Required

The ID of the task.

Responses

200

Cancellation was requested: the task's run_canceled_at timestamp is set (and its _version is incremented). The task runner watches for this flag and stops the running task as soon as possible; the runner — not this request — is what eventually moves the task to status canceled.

application/json

400

The request could not be processed. The code field of the response identifies the specific validation failure.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user is neither the task's creator nor a system.root user. Tasks are user-specific; only the user who created a task (or a system.root user) can access it. A user without the system.task system right also receives a 403.

application/json

404

No task with this id exists. The id was not loadable. Raised with code ObjectNotFound (parameters.object carries a task <id> token, e.g. task 7).

application/json

{
  "status": {
    "acknowledged": "ok"
  }
}

GET /task/{taskId}

get

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

taskIdnumber · int64Required

The ID of the task.

Responses

200

The task.

application/json

_basetypestring · enumOptionalPossible values:

created_atstring · datetimeOptional

UTC time of when the task was created.

updated_atstring · datetimeOptional

UTC time of when the task was updated.

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system.task system right (and is not system.root). Raised with code SystemRightRequired (parameters.rights lists the rights that would have satisfied the check).

application/json

404

No task with this id exists for the authenticated user. The GET /task/{taskId} operation raises code ResourceNotFound (parameters.resource carries a task <id> token).

application/json

{
  "task": {
    "_id": 1,
    "_version": 2,
    "task_module": "sleep",
    "description": "henk is super",
    "task_params": {
      "runtime": 5
    },
    "task_timeout_sec": 100,
    "next_run_at": "2026-05-30T12:00:10Z",
    "status": "new"
  },
  "_user": {
    "_generated_displayname": "root"
  }
}

PATCH /task/{taskId}

patch

Update a task. A task can only be updated if it is not in status running. The body must carry _version one higher than the stored version; a mismatch is rejected with code VersionMismatch. The task's owner (_user) is preserved and cannot be reassigned; ownership is not re-checked on update (any holder of system.task may patch any task). Updating a task whose id does not exist is reported as a 400, not a 404.

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

taskIdnumber · int64Required

The ID of the task.

Responses

200

The patched task.

application/json

_basetypestring · enumOptionalPossible values:

created_atstring · datetimeOptional

UTC time of when the task was created.

updated_atstring · datetimeOptional

UTC time of when the task was updated.

400

The request could not be processed. The code field of the response identifies the specific validation failure.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system.task system right (and is not system.root). Raised with code SystemRightRequired (parameters.rights lists the rights that would have satisfied the check).

application/json

{
  "task": {
    "_id": 1,
    "_version": 2,
    "task_module": "sleep",
    "description": "henk is super",
    "task_params": {
      "runtime": 5
    },
    "task_timeout_sec": 100,
    "next_run_at": "2026-05-30T12:00:10Z",
    "status": "new"
  },
  "_user": {
    "_generated_displayname": "root"
  }
}

DELETE /task/{taskId}

delete

Delete a task. A task in status running cannot be deleted (cancel it first); attempting to do so is rejected with a 400.

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

taskIdnumber · int64Required

The ID of the task.

Responses

200

The task was successfully deleted.

application/json

400

The request could not be processed. The code field of the response identifies the specific validation failure.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user is neither the task's creator nor a system.root user. Tasks are user-specific; only the user who created a task (or a system.root user) can access it. A user without the system.task system right also receives a 403.

application/json

404

No task with this id exists. The id was not loadable. Raised with code ObjectNotFound (parameters.object carries a task <id> token, e.g. task 7).

application/json

{
  "status": {
    "acknowledged": "ok"
  }
}

GET /task/modules

get

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Responses

200

Retrieve a list of available task modules.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user lacks the system.task system right (and is not system.root). Raised with code SystemRightRequired (parameters.rights lists the rights that would have satisfied the check).

application/json

{
  "modules": [
    {
      "name": "text",
      "displayname": {
        "de-DE": "Deutscher text",
        "en-US": "English text"
      },
      "description": {
        "de-DE": "Deutscher text",
        "en-US": "English text"
      },
      "debug": true,
      "params": [
        {
          "name": "text",
          "group": "text",
          "parameters": {
            "position": 1,
            "type": "text",
            "name": "text",
            "default": true
          },
          "require_system_right": "text",
          "unauthenticated_visible": true,
          "unavailable": true
        }
      ]
    }
  ]
}