UiPath Documentation
maestro
latest
false
Maestro Orchestrate user guide

CaseApp requests

API endpoints for triggering ad-hoc case tasks, closing case instances, listing available ad-hoc tasks, and reading a case instance and its status 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 Case instance.

POST

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

Request headers​

KeyValue
AuthorizationBearer
X-UIPATH-FolderKeyThe folder key of the case instance

Request body​

FieldTypeRequiredDescription
taskNamestringYesThe name of the ad-hoc task to trigger, exactly as it resolves in the case plan. Matching is case-sensitive.
taskInputobjectNoA 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": {}
}
{
  "taskName": "string",
  "taskInput": {}
}

Response code​

200 Success (empty body)

Error responses​

CodeMeaning
400The request body is missing or invalid.
401The caller is not authenticated.
403The caller lacks the required permission for this task.
404The 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.
500An 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 Case instance.

POST

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

Request headers​

KeyValue
AuthorizationBearer
X-UIPATH-FolderKeyThe folder key of the case instance

Response codes​

CodeMeaning
200The instance transitioned to Canceling. The worker completes the shift to Cancelled asynchronously. An already-terminal instance returns its current status unchanged.
400The instance has already reached Completed and can't be cancelled.
401The caller is not authenticated.
403The caller lacks the required permission for this instance.
404The 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​

KeyValue
AuthorizationBearer
X-UIPATH-FolderKeyThe 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.

FieldTypeDescription
stagesarrayThe stages that contain at least one task the caller can trigger.
stages[].stageIdstringThe stage's case plan node ID. Can be null.
stages[].stageLabelstringThe stage's label in the case plan.
stages[].tasksarrayThe stage's ad-hoc tasks, in case plan order.
stages[].tasks[].taskNamestringThe task's name, to pass as taskName when calling Trigger an ad-hoc case task. Matching is case-sensitive.
stages[].tasks[].taskIdstringThe 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"
        }
      ]
    }
  ]
}
{
  "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​

CodeMeaning
200The list was returned. It can be empty.
400The X-UIPATH-FolderKey header is missing or invalid.
401The caller is not authenticated.
403The caller has no Cases.RunAdhocTasks grant related to this case.
404The instance doesn't exist in the folder specified in X-UIPATH-FolderKey, or it isn't a case instance.
500The 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.

Get a case instance​

Returns a single case instance by its ID. The response has the same fields as the v3 instance list, including the case's priority, priority reason, and throttling state.

GET

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

Request headers​

KeyValue
AuthorizationBearer
X-UIPATH-FolderKeyThe folder key of the case instance

Response codes​

CodeMeaning
200The case instance was returned.
400The X-UIPATH-FolderKey header is missing or invalid.
401The caller is not authenticated.
403The caller has no Cases.View grant on this case.
404The instance doesn't exist, or it isn't a case instance.
424The authorization service couldn't be reached.
500An unexpected server error occurred.

Permissions​

Requires the Cases.View permission, granted on the case process or on any of its stages. Every case that the v3 instance list shows can be opened with this request.

Get the status of a case​

Returns the full current status of a case in one call: the case status and SLA, the current run of every stage and task the case has reached, failed task runs that haven't been run again, open stage selections, and open incidents that aren't attached to a task.

GET

{AutomationCloudURL}/{organizationName}/{tenantName}/pims_/api/v3/caseapp/instances/{instanceId}/case-status

Request headers​

KeyValue
AuthorizationBearer
X-UIPATH-FolderKeyThe folder key of the case instance

Response codes​

CodeMeaning
200The case status was returned.
400The X-UIPATH-FolderKey header is missing or invalid.
401The caller is not authenticated.
403The caller has no Cases.ViewSummary grant on this case (CaseRbacAccessDenied).
404The instance doesn't exist, or it isn't a case instance.
424The authorization service couldn't be reached (CaseRbacAuthzUnavailable).
500The case state couldn't be read, or an unexpected server error occurred.

Permissions​

Requires the Cases.ViewSummary permission on the case process. No Orchestrator folder permission is needed.

Was this page helpful?

Connect

Need help? Support(opens in new window)

Want to learn? UiPath Academy(opens in new window)

Have questions? UiPath Forum(opens in new window)

Stay updated