# Trigger a workflow

## Trigger a workflow V1

> Triggers the execution of a workflow.

```json
{"openapi":"3.0.1","info":{"title":"Workflows","version":"1.0.0"},"tags":[{"name":"Workflows"}],"servers":[{"url":"https://instance.api.region.nexthink.cloud"}],"security":[{"publicApiAuth":[]}],"components":{"securitySchemes":{"publicApiAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://instance-login.region.nexthink.cloud/oauth2/default/v1/token","scopes":{}}}}},"schemas":{"ExecutionRequest":{"required":["workflowId","users","devices"],"type":"object","properties":{"workflowId":{"type":"string","description":"The ID of the workflow to execute."},"devices":{"maxItems":10000,"type":"array","description":"Nexthink Collector IDs of the devices that the workflow should be executed on. **Note**: If `devices` are included in the request, then `users` are optional by default.\n","items":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}},"users":{"maxItems":10000,"type":"array","description":"The security IDs of the users that the workflow would target. **Note**: If `users` are included in the request, then `devices` are optional by default.\n","items":{"pattern":"^S(-\\d+){2,10}$|^0$","type":"string"}},"params":{"allOf":[{"type":"object","additionalProperties":{"type":"string"}},{"description":"Any parameters that can be sent to the workflow. If your workflow has been configured with a parameter, then `params` is optional. \nLeave the object empty if there are no parameters.\n"}]}}},"ExecutionResponse":{"required":["executionsUuids","requestUuid"],"type":"object","properties":{"requestUuid":{"minLength":1,"type":"string","description":"The request ID. Use this ID to query workflow executions in NQL `workflow.executions.request_id`."},"executionsUuids":{"minItems":1,"type":"array","description":"A list of execution ID for each object targeted `workflow.executions.execution_id`.","items":{"type":"string"}}},"description":"Each request spawns one or more executions depending on the input. All executions will have the same request ID and a unique execution ID."},"ErrorResponse":{"required":["code","details"],"type":"object","properties":{"code":{"minLength":1,"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v1/workflows/execute":{"post":{"tags":["Workflows"],"summary":"Trigger a workflow V1","description":"Triggers the execution of a workflow.","operationId":"executeEA","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"Source","in":"header","schema":{"type":"string","nullable":true}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionRequest"}}},"required":true},"responses":{"200":{"description":"Successful execution response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionResponse"}}}},"400":{"description":"Bad request - invalid request, see error code for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - no valid authentication credentials."},"403":{"description":"No permission - no permission to execute workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Trigger a workflow V2

> Triggers the execution of a workflow using external identifiers for \`users\` and \`devices\`.\
> For \`users\`, provide at least one of the following:\
> \- \`sid\`: The security identifier of the user\
> \- \`upn\`: The user's principal name (email format)\
> \- \`uid\`: A globally unique user identifier\
> For \`devices\`, provide at least one of the following:\
> \- \`collectorUid\`: The Collector UUID of the device\
> \- \`name\`: The name of the device\
> \- \`uid\`: A globally unique device identifier\
> If multiple users or devices match the identifiers, the system triggers the workflow on the most recently active one (\`lastSeen\`).<br>

```json
{"openapi":"3.0.1","info":{"title":"Workflows","version":"1.0.0"},"tags":[{"name":"Workflows"}],"servers":[{"url":"https://instance.api.region.nexthink.cloud"}],"security":[{"publicApiAuth":[]}],"components":{"securitySchemes":{"publicApiAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://instance-login.region.nexthink.cloud/oauth2/default/v1/token","scopes":{}}}}},"schemas":{"ExternalIdsExecutionRequest":{"required":["workflowId","users","devices"],"type":"object","properties":{"workflowId":{"type":"string","description":"The ID of the workflow to execute."},"devices":{"maxItems":10000,"type":"array","description":"Nexthink Collector IDs, device names and/or device UIDs of the devices that the workflow should be executed on.","items":{"$ref":"#/components/schemas/DeviceData"}},"users":{"maxItems":10000,"type":"array","description":"User's Security IDs, user's principal name and/or users UIDs that the workflow would target.","items":{"$ref":"#/components/schemas/UserData"}},"params":{"allOf":[{"type":"object","additionalProperties":{"type":"string"}},{"description":"Any parameters to send to the workflow. Leave the object empty if there are none."}]}}},"DeviceData":{"type":"object","properties":{"name":{"type":"string"},"uid":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"collectorUid":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}},"UserData":{"type":"object","properties":{"uid":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"upn":{"pattern":"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$","type":"string"},"sid":{"pattern":"^S(-\\d+){2,10}$|^0$","type":"string"}}},"ExecutionResponse":{"required":["executionsUuids","requestUuid"],"type":"object","properties":{"requestUuid":{"minLength":1,"type":"string","description":"The request ID. Use this ID to query workflow executions in NQL `workflow.executions.request_id`."},"executionsUuids":{"minItems":1,"type":"array","description":"A list of execution ID for each object targeted `workflow.executions.execution_id`.","items":{"type":"string"}}},"description":"Each request spawns one or more executions depending on the input. All executions will have the same request ID and a unique execution ID."},"ErrorResponse":{"required":["code","details"],"type":"object","properties":{"code":{"minLength":1,"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v2/workflows/execute":{"post":{"tags":["Workflows"],"summary":"Trigger a workflow V2","description":"Triggers the execution of a workflow using external identifiers for `users` and `devices`.\nFor `users`, provide at least one of the following:\n- `sid`: The security identifier of the user\n- `upn`: The user's principal name (email format)\n- `uid`: A globally unique user identifier\nFor `devices`, provide at least one of the following:\n- `collectorUid`: The Collector UUID of the device\n- `name`: The name of the device\n- `uid`: A globally unique device identifier\nIf multiple users or devices match the identifiers, the system triggers the workflow on the most recently active one (`lastSeen`).\n","operationId":"executeEAWithExternalIds","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"Source","in":"header","schema":{"type":"string","nullable":true}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalIdsExecutionRequest"}}},"required":true},"responses":{"200":{"description":"Successful execution response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionResponse"}}}},"400":{"description":"Bad request - invalid request, see error code for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - no valid authentication credentials."},"403":{"description":"No permission - no permission to execute workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Trigger wait for event

> Triggers a waiting workflow execution.

```json
{"openapi":"3.0.1","info":{"title":"Workflows","version":"1.0.0"},"tags":[{"name":"Workflows"}],"servers":[{"url":"https://instance.api.region.nexthink.cloud"}],"security":[{"publicApiAuth":[]}],"components":{"securitySchemes":{"publicApiAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://instance-login.region.nexthink.cloud/oauth2/default/v1/token","scopes":{}}}}},"schemas":{"ThinkletTriggerRequest":{"type":"object","properties":{"parameters":{"allOf":[{"type":"object","additionalProperties":{"minLength":1,"type":"string"}},{"description":"Any parameters to send to the thinklet waiting for this trigger. Leave the object empty if there are none."}]}}},"ThinkletTriggerResponse":{"required":["requestUuid"],"type":"object","properties":{"requestUuid":{"type":"string","description":"The request ID.","format":"uuid"}}},"ErrorResponse":{"required":["code","details"],"type":"object","properties":{"code":{"minLength":1,"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v1/workflows/workflows/{workflowUuid}/execution/{executionUuid}/trigger":{"post":{"tags":["Workflows"],"summary":"Trigger wait for event","description":"Triggers a waiting workflow execution.","operationId":"triggerThinklet","parameters":[{"name":"Source","in":"header","schema":{"type":"string","nullable":true}},{"name":"workflowUuid","in":"path","required":true,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}},{"name":"executionUuid","in":"path","required":true,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThinkletTriggerRequest"}}},"required":true},"responses":{"200":{"description":"Returns a request identifier.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ThinkletTriggerResponse"}}}}},"400":{"description":"Bad request - invalid request, see error code for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - no valid authentication credentials."},"403":{"description":"No permission - not authorized to execute workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## List workflows

> Returns a list of workflows, including their configuration information. Use query parameters to filter the list of the workflows.

```json
{"openapi":"3.0.1","info":{"title":"Workflows","version":"1.0.0"},"tags":[{"name":"Workflows"}],"servers":[{"url":"https://instance.api.region.nexthink.cloud"}],"security":[{"publicApiAuth":[]}],"components":{"securitySchemes":{"publicApiAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://instance-login.region.nexthink.cloud/oauth2/default/v1/token","scopes":{}}}}},"schemas":{"WorkflowFilter.WorkflowDependency":{"type":"string","enum":["USER","DEVICE","USER_AND_DEVICE","NONE"]},"WorkflowFilter.TriggerMethod":{"type":"string","enum":["API","MANUAL","MANUAL_MULTIPLE","SCHEDULER"]},"Workflow":{"required":["description","id","lastUpdateTime","name","status","triggerMethods","uuid","versions"],"type":"object","properties":{"id":{"type":"string"},"uuid":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"$ref":"#/components/schemas/Workflow.Status"},"lastUpdateTime":{"type":"string","format":"date-time"},"triggerMethods":{"$ref":"#/components/schemas/Workflow"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"}}}},"Workflow.Status":{"type":"string","enum":["ACTIVE","INACTIVE"]},"ErrorResponse":{"required":["code","details"],"type":"object","properties":{"code":{"minLength":1,"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v1/workflows":{"get":{"tags":["Workflows"],"summary":"List workflows","description":"Returns a list of workflows, including their configuration information. Use query parameters to filter the list of the workflows.","operationId":"getAllWorkflows","parameters":[{"name":"dependency","in":"query","required":true,"schema":{"$ref":"#/components/schemas/WorkflowFilter.WorkflowDependency"}},{"name":"triggerMethod","in":"query","required":true,"schema":{"$ref":"#/components/schemas/WorkflowFilter.TriggerMethod"}},{"name":"fetchOnlyActiveWorkflows","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"Source","in":"header","schema":{"type":"string","nullable":true}}],"responses":{"200":{"description":"List of workflows and their configurations.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"}}}}},"400":{"description":"Bad request - invalid request, see error code for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - no valid authentication credentials."},"403":{"description":"No permission - not authorized to execute workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get workflow

> Returns the configuration of a specific workflow by NQL ID. Use \`nqlId\` to filter for a specific configured workflow.

```json
{"openapi":"3.0.1","info":{"title":"Workflows","version":"1.0.0"},"tags":[{"name":"Workflows"}],"servers":[{"url":"https://instance.api.region.nexthink.cloud"}],"security":[{"publicApiAuth":[]}],"components":{"securitySchemes":{"publicApiAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://instance-login.region.nexthink.cloud/oauth2/default/v1/token","scopes":{}}}}},"schemas":{"Workflow":{"required":["description","id","lastUpdateTime","name","status","triggerMethods","uuid","versions"],"type":"object","properties":{"id":{"type":"string"},"uuid":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"$ref":"#/components/schemas/Workflow.Status"},"lastUpdateTime":{"type":"string","format":"date-time"},"triggerMethods":{"$ref":"#/components/schemas/Workflow"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"}}}},"Workflow.Status":{"type":"string","enum":["ACTIVE","INACTIVE"]},"ErrorResponse":{"required":["code","details"],"type":"object","properties":{"code":{"minLength":1,"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v1/workflows/details":{"get":{"tags":["Workflows"],"summary":"Get workflow","description":"Returns the configuration of a specific workflow by NQL ID. Use `nqlId` to filter for a specific configured workflow.","operationId":"getWorkflow","parameters":[{"name":"nqlId","in":"query","description":"The NQL ID of the workflow.","required":true,"schema":{"type":"string"}},{"name":"Source","in":"header","schema":{"type":"string","nullable":true}}],"responses":{"200":{"description":"Workflow configuration.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"}}}}},"400":{"description":"Bad request - invalid request, see error code for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - no valid authentication credentials."},"403":{"description":"No permission - no permission to execute workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```