API for robots

Access and manage robot-related data through the GraphQL API using the Nintex endpoint. These APIs include operations such as retrieving pending robots, getting information on approved robots, stopping and starting robots, assigning robots to queues, and approving robots.

Before you begin:

Learn the fundamentals of GraphQL, the query language used to request and manage data through the Nintex public API.
Understand how to create effective queries and mutations to make requests and interact with the API.
Learn how to get and authenticate an access token.
Discover and understand the available endpoints.

Schema overview

The GraphQL API schema is a blueprint outlining the structure and functionality of the public APIs. The schema provides a clear overview of available data types, queries, and mutations, offering a foundation for understanding how to interact with the APIs effectively.

In GraphQL, using square brackets [ ] indicates a list, and the exclamation mark ! means non-nullable.

[Status!]!: The outer ! ensures that the API always returns a list (even if it's empty), and that the returned list will not be null.

Status!: The inner ! ensures that each element within the list is a non-nullable Status object. This guarantees that there won't be null values within the list, and any attempt to include null values would result in a failed query.

Schema

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
type GetApprovedRobotsResponse {
  items: [Robot]
  totalRecords: Int!
}

type Robot {
  id: String!
  name: String!
  createTime: DateTime
  machineName: String!
  fullOsUsername: String!
  hasOsPassword: Boolean
  osVersion: String!
  state: String!
  tags: [Tag]
  doAutologin: Boolean!
  stopOnWizardError: Boolean!
  unlockMode: Boolean!
  secretErrorCode: SecretErrorCode
}

enum SecretErrorCode { 
  ACCOUNT_NOT_FOUND
DOMAIN_DOES_NOT_MATCH
USERNAME_DOES_NOT_MATCH
DOMAIN_AND_USERNAME_DO_NOT_MATCH
LOGIN_FAILURE
CONNECTION_FAILURE
GENERAL_ERROR
}

enum StopType {
  STOP_IMMEDIATELY
  STOP_GRACEFULLY 
}

type Tag {
  id: ID!
  name: String!
}

input AuditDetailsInput {
  clientTime: DateTime!
  clientTimezone: String!
  clientName: String!
  reason: String!
}

input StopRobotInput {
  id: ID!
  stopType: StopType
}

input AssignQueuesInput {
    robotId: String!
    queuesIds: [String!]!
}

type GetPendingRobotsResponse {
  items: [PendingRobot]
  totalRecords: Int!
}

type PendingRobot {
  id: String!
  rejected: Boolean!
  createTime: DateTime!
  machineName: String!
  fullOsUsername: String!
  osVersion: String
  osDomain: String
  osUsername: String
}

input ApprovePendingRobotInput {
  id: String!
  name: String
  password: String
  externalKey: String
}
  
extend type Query {
  getPendingRobots(queryInput: QueryInput!): GetPendingRobotsResponse
  getApprovedRobots(queryInput: QueryInput!, auditDetails: AuditDetailsInput!): GetApprovedRobotsResponse
  getApprovedRobot(robotId: ID!, auditDetails: AuditDetailsInput!): Robot
}

extend type Mutation {
  approveRobot(input: ApprovePendingRobotInput, auditDetails: AuditDetailsInput): Boolean
  startRobot(id: ID!): Boolean
  stopRobot(stopRobot: StopRobotInput!): Boolean
  assignRobotToQueue(input: AssignQueuesInput!): Boolean
}

API requests

The following API requests provide the ability to manage robots and approvals using the Nintex endpoint:

Get pending robots

Copy

QUERY

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
query($queryInput: QueryInput!) {
  getPendingRobots(queryInput: $queryInput) {
      items {
        id
        rejected
        createTime
        machineName
        fullOsUsername
        osVersion
        osDomain
        osUsername
    },
        totalRecords
    }

)

Copy

GRAPHQL VARIABLES

1
2
3
4
5
6
{
  queryInput: {
     filter: {},
     sort: []
  }
}

Copy

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
    "data": {
        "getPendingRobots": {
            "items": [
                {
                    "id": "cd55bb7b-e623-4792-8694-c9a60e64bffc",
                    "rejected": false,
                    "createTime": "2022-09-29T10:10:24.743Z",
                    "machineName": "VMC-09-13-42-14",
                    "fullOsUsername": "Administrator@VMC-09-13-42-14",
                    "osVersion": "Microsoft Windows Server 2019 Standard",
                    "osDomain": "VMC-09-13-42-14",
                    "osUsername": "Administrator"
                },
                {
                    "id": "979b696c-ec1b-46f7-86ad-295246db4481",
                    "rejected": false,
                    "createTime": "2022-09-28T16:01:36.243Z",
                    "machineName": "VMC-09-13-42-14",
                    "fullOsUsername": "dev@kryonaws",
                    "osVersion": "Microsoft Windows Server 2019 Standard",
                    "osDomain": "kryonaws",
                    "osUsername": "dev"
                },
                {
                    "id": "21a593b6-4d14-4606-98a3-ba706e03084a",
                    "rejected": false,
                    "createTime": "2022-09-28T14:31:23.330Z",
                    "machineName": "VMC-09-13-42-14",
                    "fullOsUsername": "dev@kryonaws",
                    "osVersion": "Microsoft Windows Server 2019 Standard",
                    "osDomain": "kryonaws",
                    "osUsername": "dev"
                },
                {
                    "id": "00a35d8e-ad9f-4d5d-b475-0c378b0507e8",
                    "rejected": false,
                    "createTime": "2022-09-28T14:32:32.580Z",
                    "machineName": "VMC-09-13-42-14",
                    "fullOsUsername": "dev@kryonaws",
                    "osVersion": "Microsoft Windows Server 2019 Standard",
                    "osDomain": "kryonaws",
                    "osUsername": "dev"
                }
            ],
            "totalRecords": 4
        }
    }
}

Get approved robot: single by ID

Copy

QUERY

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
query($robotId: ID!, $auditDetails: AuditDetailsInput!) {
  getApprovedRobot(robotId: $robotId, auditDetails: $auditDetails) {
        id
        name
        createTime
        machineName
        fullOsUsername
        hasOsPassword
        osVersion
        state
        tags {
            id
            name
        }
        doAutologin
        stopOnWizardError
        unlockMode
        secretErrorCode
    }
}

Copy

GRAPHQL VARIABLES

1
2
3
4
5
6
7
8
9
{
  robotId: "cd55bb7b-e623-4792-8694-c9a60e64bffc",
  auditDetails: {
     clientTime: "2022-07-24T08:58:34.489Z",
     clientTimezone: "UTC",
     clientName: "NintexPublicApi",
     reason: "Tests"
  }
}

Copy

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "data": {
        "getApprovedRobot": {
            "id": "cd55bb7b-e623-4792-8694-c9a60e64bffc",
            "name": "Robot4_cd55bb7b-e623-4792-8694-c9a60e64bffc",
            "createTime": "2022-09-29T11:20:31.173Z",
            "machineName": "VMC-09-13-42-14",
            "fullOsUsername": "Administrator@VMC-09-13-42-14",
            "hasOsPassword": false,
            "osVersion": "Microsoft Windows Server 2019 Standard",
            "state": "disconnected",
            "tags": [],
            "doAutologin": false,
            "stopOnWizardError": false,
            "unlockMode": false,
            "secretErrorCode": null
        }
    }
}

Get approved robots: all

Copy

QUERY

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
query($queryInput: QueryInput!, $auditDetails: AuditDetailsInput!) {
  getApprovedRobots(queryInput: $queryInput, auditDetails: $auditDetails) {
      items {
            id
            name
            createTime
            machineName
            fullOsUsername
            hasOsPassword
            osVersion
            state
            tags {
                id
                name
            }
            doAutologin
            stopOnWizardError
            unlockMode
            secretErrorCode
        },
        totalRecords
    }
}

Copy

GRAPHQL VARIABLES

1
2
3
4
5
6
7
8
9
10
11
12
{
  queryInput: {
        filter: {},
        sort: []
    },
    auditDetails: {
        clientTime: "2022-07-24T08:58:34.489Z",
        clientTimezone: "UTC",
        clientName: "NintexPublicApi",
        reason: "Tests"
    }
}

Copy

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
    "data": {
        "getApprovedRobots": {
            "items": [
                {
                    "id": "cd55bb7b-e623-4792-8694-c9a60e64bffc",
                    "name": "Robot4_cd55bb7b-e623-4792-8694-c9a60e64bffc",
                    "createTime": "2022-09-29T11:20:31.173Z",
                    "machineName": "VMC-09-13-42-14",
                    "fullOsUsername": "Administrator@VMC-09-13-42-14",
                    "hasOsPassword": false,
                    "osVersion": "Microsoft Windows Server 2019 Standard",
                    "state": "disconnected",
                    "tags": [
                        {
                            "id": "8f37c868-8bfb-4140-9828-6202924a9618",
                            "name": "tanin"
                        },
                        {
                            "id": "c3811977-df13-4842-948b-2938a7cdbb63",
                            "name": "etrog"
                        },
                        {
                            "id": "ee4056e9-9ffb-4751-839a-d66d0e6bd5c8",
                            "name": "timsah"
                        }
                    ],
                    "doAutologin": false,
                    "stopOnWizardError": false,
                    "unlockMode": false,
                    "secretErrorCode": null
                },
                {
                    "id": "979b696c-ec1b-46f7-86ad-295246db4481",
                    "name": "Robot_979b696c-ec1b-46f7-86ad-295246db4481",
                    "createTime": "2022-09-29T11:49:51.637Z",
                    "machineName": "VMC-09-13-42-14",
                    "fullOsUsername": "dev@kryonaws",
                    "hasOsPassword": true,
                    "osVersion": "Microsoft Windows Server 2019 Standard",
                    "state": "disconnected",
                    "tags": [],
                    "doAutologin": false,
                    "stopOnWizardError": false,
                    "unlockMode": false,
                    "secretErrorCode": null
                },
                {
                    "id": "21a593b6-4d14-4606-98a3-ba706e03084a",
                    "name": "Robot_21a593b6-4d14-4606-98a3-ba706e03084a",
                    "createTime": "2022-09-29T11:23:02.277Z",
                    "machineName": "VMC-09-13-42-14",
                    "fullOsUsername": "dev@kryonaws",
                    "hasOsPassword": true,
                    "osVersion": "Microsoft Windows Server 2019 Standard",
                    "state": "disconnected",
                    "tags": [],
                    "doAutologin": false,
                    "stopOnWizardError": false,
                    "unlockMode": false,
                    "secretErrorCode": null
                }
            ],
            "totalRecords": 3
        }
    }
}

Stop robots

Copy

QUERY

1
2
3
mutation($stopRobot: StopRobotInput!) {
  stopRobot(stopRobot: $stopRobot)
}

Copy

GRAPHQL VARIABLES

1
2
3
4
5
6
{
  stopRobot: {
    id: "{{ROBOT_ID4}}", 
    stopType: STOP_IMMEDIATELY 
  }
}

Copy

RESPONSE

1
2
3
4
5
{
    "data": {
        "stopRobot": true
    }
}

Start robot

Copy

QUERY

1
2
3
mutation($id: ID!) {
  startRobot(id: $id)
}

Copy

GRAPHQL VARIABLES

1
2
3
{
  id: "{{ROBOT_ID4}}"
}

Copy

RESPONSE

1
2
3
4
5
{
    "data": {
        "startRobot": true
    }
}

Assign robot to queue

Copy

QUERY

1
2
3
mutation($input: AssignQueuesInput!) {
  assignRobotToQueue(input: $input)
}

Copy

GRAPHQL VARIABLES

1
2
3
4
5
6
{
  input: {
    robotId: "{{ROBOT_ID4}}",
    queuesIds: ["{{QUEUE_ID1}}","{{QUEUE_ID4}}","{{QUEUE_ID3}}"]
  }
}

Copy

RESPONSE

1
2
3
4
5
{
    "data": {
        "assignRobotToQueue": true
    }
}

Approve robot

Copy

QUERY

1
2
3
mutation($input: ApprovePendingRobotInput, $auditDetails: AuditDetailsInput) {
  approveRobot(input: $input, auditDetails: $auditDetails)
}

Copy

GRAPHQL VARIABLES

1
2
3
4
5
6
7
8
9
10
11
12
{
  input: {
    id: "{{ROBOT_ID4}}",
    name: "{{ROBOT_NAME4}}"
  },
  auditDetails: {
    clientTime: "2022-07-24T08:58:34.489Z",
    clientTimezone: "UTC",
    clientName: "NintexPublicApi",
    reason: "Tests"
  }
}

Copy

RESPONSE

1
2
3
4
5
{
    "data": {
        "approveRobot": true
    }
}