Version: Next

Tasks API

Use the Tasks API to list visible work, claim shared tasks, inspect task context, and complete user tasks.

Operations

Method	Path	Summary
`GET`	`/tasks`	Get all tasks
`GET`	`/tasks/{id}`	Get task by ID
`PUT`	`/tasks/{id}/assignee`	Reassign a task
`POST`	`/tasks/{id}/claim`	Claim a task
`POST`	`/tasks/{id}/complete`	Complete a task
`POST`	`/tasks/{id}/draft`	Save a task draft
`POST`	`/tasks/{id}/unclaim`	Unclaim a task
`GET`	`/tasks/search`	Search tasks
`POST`	`/tasks/search`	Search tasks with structured filters

GET /tasks

Get all tasks

Retrieve all tasks with pagination

Completed task rows continue to return their last saved task variable snapshot until maintenance cleanup removes the task record.

Property	Value
Operation ID	`getTasks`
Auth	Bearer token required unless security is disabled.
Response DTO	PageTaskResponseDto

Completed task entries keep their submitted variables in the response so historical task reviews can show the final task payload.

Parameters

Name	In	Required	Type	Description
`pageable`	query	Yes	Pageable

Example request

curl -X GET "http://localhost:8080/tasks?page=0&size=20" \
  -H "Authorization: Bearer $TOKEN"

Responses

Status	Description	Schema
`200`	OK	PageTaskResponseDto

Example response

Status: 200 OK

{
  "content": [
    {
      "id": 123,
      "title": "Manager Review",
      "name": "Manager Review",
      "description": "Review the expense request.",
      "processInstanceId": 456,
      "nodeId": "manager-review",
      "assignee": "manager",
      "candidateUsers": [],
      "candidateGroups": [
        "FINANCE"
      ],
      "status": "PENDING",
      "createdAt": "2026-06-17T09:30:00",
      "completedAt": null,
      "formDbId": 12,
      "formId": "expenseReview",
      "variables": {
        "amount": 1250.75,
        "requester": "Alice"
      }
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "first": true,
  "last": true,
  "size": 20,
  "number": 0,
  "numberOfElements": 1,
  "empty": false,
  "sort": {
    "empty": true,
    "sorted": false,
    "unsorted": true
  },
  "pageable": {
    "offset": 0,
    "pageNumber": 0,
    "pageSize": 20,
    "paged": true,
    "unpaged": false,
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    }
  }
}

GET /tasks/{id}

Get task by ID

Retrieve a specific task by its ID

If the task is already COMPLETED, the response still includes the last saved task variables until the task is purged by retention cleanup or an explicit maintenance purge.

Property	Value
Operation ID	`getTaskById`
Auth	Bearer token required unless security is disabled.
Response DTO	TaskResponseDto

Completed task responses continue to include the task's submitted variables after the task finishes. Use this endpoint when operators or client apps need to review the final task payload.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	integer(int64)

Example request

curl -X GET "http://localhost:8080/tasks/123" \
  -H "Authorization: Bearer $TOKEN"

Responses

Status	Description	Schema
`200`	OK	TaskResponseDto

Example response

Status: 200 OK

{
  "id": 123,
  "title": "Manager Review",
  "name": "Manager Review",
  "description": "Review the expense request.",
  "processInstanceId": 456,
  "nodeId": "manager-review",
  "assignee": "manager",
  "candidateUsers": [],
  "candidateGroups": [
    "FINANCE"
  ],
  "status": "PENDING",
  "createdAt": "2026-06-17T09:30:00",
  "completedAt": null,
  "formDbId": 12,
  "formId": "expenseReview",
  "variables": {
    "amount": 1250.75,
    "requester": "Alice"
  }
}

POST /tasks/{id}/claim

Claim a task

Claim a shared/group task for the current authenticated user

Property	Value
Operation ID	`claimTask`
Auth	Bearer token required unless security is disabled.
Response DTO	TaskResponseDto

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	integer(int64)

Example request

curl -X POST "http://localhost:8080/tasks/123/claim" \
  -H "Authorization: Bearer $TOKEN"

Responses

Status	Description	Schema
`200`	OK	TaskResponseDto

Example response

Status: 200 OK

{
  "id": 123,
  "title": "Manager Review",
  "name": "Manager Review",
  "description": "Review the expense request.",
  "processInstanceId": 456,
  "nodeId": "manager-review",
  "assignee": "admin",
  "candidateUsers": [],
  "candidateGroups": [
    "FINANCE"
  ],
  "status": "PENDING",
  "createdAt": "2026-06-17T09:30:00",
  "completedAt": null,
  "formDbId": 12,
  "formId": "expenseReview",
  "variables": {
    "amount": 1250.75,
    "requester": "Alice"
  }
}

POST /tasks/{id}/complete

Complete a task

Mark a task as completed and provide task variables

Property	Value
Operation ID	`completeTask`
Auth	Bearer token required unless security is disabled.
Request DTO	`Task completion payload`
Request content type	`application/json`
Response DTO	`string`

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	integer(int64)

Request body

Required	Content type	DTO/schema
Yes	`application/json`	`Task completion payload`

Example request body:

{
  "variables": {
    "approved": true,
    "comment": "Approved for payment",
    "reviewedAt": "2026-06-17T10:00:00Z"
  }
}

Example request

curl -X POST "http://localhost:8080/tasks/123/complete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "variables": {
    "approved": true,
    "comment": "Approved for payment",
    "reviewedAt": "2026-06-17T10:00:00Z"
  }
}'

Responses

Status	Description	Schema
`200`	OK	`string`

Example response

Status: 200 OK

Task completed successfully

POST /tasks/{id}/unclaim

Removes the current assignee and returns the task to the available pool.

curl -X POST "http://localhost:8080/tasks/123/unclaim" \
  -H "Authorization: Bearer $TOKEN"

The response is the updated TaskResponseDto.

POST /tasks/{id}/draft

Persists task variables without completing the task. Use this when a user saves progress in the Task Portal and needs to continue later.

curl -X POST "http://localhost:8080/tasks/123/draft" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "amount": 1250.75,
      "comment": "Waiting for receipt",
      "approved": false
    }
  }'

The response is the updated TaskResponseDto.

PUT /tasks/{id}/assignee

Reassigns an existing task. This is an administrative operation for changing the assignee explicitly.

curl -X PUT "http://localhost:8080/tasks/123/assignee" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assignee": "manager"
  }'

The response is the updated TaskResponseDto.

GET /tasks/search

Searches tasks with query parameters. Use this for simple filters from browser clients or quick operational checks.

curl -X GET "http://localhost:8080/tasks/search?status=PENDING&assignee=manager&page=0&size=20" \
  -H "Authorization: Bearer $TOKEN"

The response is a paged PageTaskResponseDto.

POST /tasks/search

Search tasks

Search tasks with structured filters and pagination.

Filters are combined with AND. The endpoint respects the caller's visibility rules, so non-admin users only see tasks assigned to them or available to their groups.

Supported filter fields:

Field	Notes
`status` / `state`	Task status such as `PENDING` or `COMPLETED`.
`assignee`	Task assignee. Use `UNASSIGNED` to match empty assignees.
`candidateUser` / `candidate_user`	Candidate user membership.
`candidateGroup` / `candidate_group`	Candidate group membership.
`processInstance` / `processInstanceId` / `process_instance_id`	Process instance id.
`processDefinition` / `processDefinitionId` / `process_definition_id` / `processDefinitionKey` / `process_definition_key`	Process definition id, key, or name.
`taskName` / `task_name` / `title` / `name`	Task title.
`createdAt` / `created_at` / `createdDate` / `created_date`	Task creation timestamp or date.
`variable`	Task or process variable, addressed by `name` and `scope`.

Supported operators:

Operator	Notes
`EQUALS`, `NOT_EQUALS`	Exact match.
`IN`, `NOT_IN`	Match against multiple values.
`GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`	Numeric or date comparisons.
`CONTAINS`, `STARTS_WITH`, `ENDS_WITH`	Case-insensitive string matching.

Completed task responses continue to include the last saved task variable snapshot until maintenance cleanup removes the task record.

Property	Value
Operation ID	`searchTasks`
Auth	Bearer token required unless security is disabled.
Response DTO	PageTaskResponseDto

Request body

Required	Content type	DTO/schema
Yes	`application/json`	TaskSearchRequestDto

Example request body:

{
  "filters": [
    {
      "field": "status",
      "operator": "EQUALS",
      "value": "PENDING"
    },
    {
      "field": "taskName",
      "operator": "CONTAINS",
      "value": "review"
    }
  ]
}

Parameters

Name	In	Required	Type	Description
`pageable`	query	Yes	Pageable

Example request

curl -X POST "http://localhost:8080/tasks/search?page=0&size=20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "filters": [
      { "field": "status", "operator": "EQUALS", "value": "PENDING" },
      { "field": "assignee", "operator": "EQUALS", "value": "manager" }
    ]
  }'

Responses

Status	Description	Schema
`200`	OK	PageTaskResponseDto

Example response

Status: 200 OK

{
  "content": [
    {
      "id": 123,
      "title": "Manager Review",
      "name": "Manager Review",
      "description": "Review the expense request.",
      "processInstanceId": 456,
      "nodeId": "manager-review",
      "assignee": "manager",
      "candidateUsers": [],
      "candidateGroups": [
        "FINANCE"
      ],
      "status": "PENDING",
      "createdAt": "2026-06-17T09:30:00",
      "completedAt": null,
      "formDbId": 12,
      "formId": "expenseReview",
      "variables": {
        "amount": 1250.75,
        "requester": "Alice"
      }
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "first": true,
  "last": true,
  "size": 20,
  "number": 0,
  "numberOfElements": 1,
  "empty": false,
  "sort": {
    "empty": true,
    "sorted": false,
    "unsorted": true
  },
  "pageable": {
    "offset": 0,
    "pageNumber": 0,
    "pageSize": 20,
    "paged": true,
    "unpaged": false,
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    }
  }
}

Operations​

GET /tasks​

Parameters​

Example request​

Responses​

Example response​

GET /tasks/{id}​

Parameters​

Example request​

Responses​

Example response​

POST /tasks/{id}/claim​

Parameters​

Example request​

Responses​

Example response​

POST /tasks/{id}/complete​

Parameters​

Request body​

Example request​

Responses​

Example response​

POST /tasks/{id}/unclaim​

POST /tasks/{id}/draft​

PUT /tasks/{id}/assignee​

GET /tasks/search​

POST /tasks/search​

Request body​

Parameters​

Example request​

Responses​

Example response​

Operations

GET /tasks

Parameters

Example request

Responses

Example response

GET /tasks/{id}

Parameters

Example request

Responses

Example response

POST /tasks/{id}/claim

Parameters

Example request

Responses

Example response

POST /tasks/{id}/complete

Parameters

Request body

Example request

Responses

Example response

POST /tasks/{id}/unclaim

POST /tasks/{id}/draft

PUT /tasks/{id}/assignee

GET /tasks/search

POST /tasks/search

Request body

Parameters

Example request

Responses

Example response