CaseApp requests

API endpoints for triggering ad-hoc case tasks, closing case instances, and listing available ad-hoc tasks through the CaseApp v3 API.

Trigger an ad-hoc case task

Triggers one manually-triggered (ad-hoc) task, identified by its case plan name, on a running Maestro Case instance.

POST

{AutomationCloudURL}/{organizationName}/{tenantName}/pims_/api/v3/caseapp/instances/{instanceId}/tasks/trigger

Request headers

Key	Value
Authorization	Bearer
X-UIPATH-FolderKey	The folder key of the case instance

Request body

Field	Type	Required	Description
taskName	string	Yes	The name of the ad-hoc task to trigger, exactly as it resolves in the case plan. Matching is case-sensitive.
taskInput	object	No	A free-form JSON object forwarded verbatim to the triggered task as a nested payload, for example approval references or decision data. The platform doesn't interpret or schema-validate this payload, and it isn't bound to the task's declared inputs.

{
  "taskName": "string",
  "taskInput": {}
}

Response code

200 Success (empty body)

Error responses

Code	Meaning
400	The request body is missing or invalid.
401	The caller is not authenticated.
403	The caller lacks the required permission for this task.
404	The case instance doesn't exist, or no ad-hoc task with that name exists on the case plan. Only tasks with an "adhoc" entry condition are eligible — other names return 404.
500	An unexpected server error occurred.

Permissions

Requires the Cases.RunAdhocTasks permission, authorized at the scope of the stage that owns the requested task.

Close a case instance

Closes a running Maestro Case instance.

POST

{AutomationCloudURL}/{organizationName}/{tenantName}/pims_/api/v3/caseapp/instances/{instanceId}/close

Request headers

Key	Value
Authorization	Bearer
X-UIPATH-FolderKey	The folder key of the case instance

Response codes

Code	Meaning
200	The instance transitioned to Canceling. The worker completes the shift to Cancelled asynchronously. An already-terminal instance returns its current status unchanged.
400	The instance has already reached Completed and can't be cancelled.
401	The caller is not authenticated.
403	The caller lacks the required permission for this instance.
404	The instance ID doesn't resolve to a case instance.

Permissions

Requires the Cases.Close persona grant.

List the ad-hoc tasks you can run on a case

Lists the ad-hoc tasks a caller is permitted to trigger on a case instance, grouped by the stage that owns each task.

GET

{AutomationCloudURL}/{organizationName}/{tenantName}/pims_/api/v3/caseapp/instances/{instanceId}/tasks/adhoc

Request headers

Key	Value
Authorization	Bearer
X-UIPATH-FolderKey	The folder key of the case instance

Response body

Returns the ad-hoc tasks the caller can trigger, grouped by the stage that owns them. Stages without a task the caller can trigger are omitted, so an empty stages list means the caller can't trigger any task on this case.

Field	Type	Description
stages	array	The stages that contain at least one task the caller can trigger.
stages[].stageId	string	The stage's case plan node ID. Can be null.
stages[].stageLabel	string	The stage's label in the case plan.
stages[].tasks	array	The stage's ad-hoc tasks, in case plan order.
stages[].tasks[].taskName	string	The task's name, to pass as taskName when calling Trigger an ad-hoc case task. Matching is case-sensitive.
stages[].tasks[].taskId	string	The task's case plan node ID. Can be null. The trigger endpoint doesn't accept it.

{
  "stages": [
    {
      "stageId": "string",
      "stageLabel": "string",
      "tasks": [
        {
          "taskName": "string",
          "taskId": "string"
        }
      ]
    }
  ]
}

A listed task is one the caller is authorized to trigger, but the trigger can still fail. For example, triggering a task on a completed case returns 404.

Response codes

Code	Meaning
200	The list was returned. It can be empty.
400	The X-UIPATH-FolderKey header is missing or invalid.
401	The caller is not authenticated.
403	The caller has no Cases.RunAdhocTasks grant related to this case.
404	The instance doesn't exist in the folder specified in X-UIPATH-FolderKey, or it isn't a case instance.
500	The case plan couldn't be read, or an unexpected server error occurred.

Permissions

Requires the Cases.RunAdhocTasks permission, authorized at the scope of the stage that owns each listed task.