The Agent Pools API provides operations to manage the update settings of the directory agents for your org.
Lists all agent pools with pagination support
limitPerPoolType | integer Default: 5 Maximum number of agent pools returned |
poolType | string (AgentType) Agent type to search for |
after | string The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the |
OK
Forbidden
Too Many Requests
[- {
- "disruptedAgents": 0,
- "inactiveAgents": 1,
- "operationalStatus": "OPERATIONAL",
- "id": "poolId1",
- "name": "region1A.dc",
- "type": "AD",
- "agents": {
- "id": "agentId1",
- "state": "ACTIVE",
- "message": "Agent connection is live",
- "indicator": "green",
- "name": "WIN-region1A-dc",
- "version": "3.18.0",
- "upgradeRequired": false,
- "active": true,
- "supportAutoUpdate": true,
- "errorState": true,
- "isHidden": false,
- "isLatestGAedVersion": false,
- "lastConnection": 1628263766000,
- "operationalStatus": "OPERATIONAL",
- "poolId": "poolId1",
- "updateMessage": "Queued for update."
}, - "_links": {
- "self": {
- "href": "/api/v1/agentPools/poolId1"
}
}
}
]
Lists all agent pool updates
OK
Forbidden
Not Found
Too Many Requests
[- {
- "id": "poolId1",
- "name": "testSchedule",
- "agentType": "AD",
- "agents": {
- "latestGAedVersion": true,
- "id": "a533eu8npxdZ60Mvf5s6",
- "type": "AD",
- "operationalStatus": "OPERATIONAL",
- "updateStatus": "Scheduled",
- "updateMessage": "Queued for update.",
- "version": "3.20.0",
- "lastConnection": 1750462090000,
- "isLatestGAedVersion": true,
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "name": "N079-H069",
- "isHidden": false
}, - "enabled": true,
- "schedule": {
- "cron": "0 1 * * THU",
- "timezone": "America/Los_Angeles",
- "duration": 420
}, - "notifyAdmin": true,
- "status": "Scheduled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "href": "/api/v1/agentPools/poolId1/updates"
}
}
}
]
Creates an agent pool update
Created
Bad Request
Forbidden
Not Found
Too Many Requests
{- "agents": [
- {
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0"
}
], - "agentType": "AD",
- "enabled": true,
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0"
}
{- "agents": [
- {
- "id": "ajd3fxzltQKQ2VeLu5s6",
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
], - "agentType": "AD",
- "enabled": true,
- "id": "string",
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
Retrieves the current state of the agent pool update instance settings
OK
Forbidden
Not Found
Too Many Requests
{- "agentType": "AD",
- "continueOnError": true,
- "latestVersion": "3.20.0",
- "minimalSupportedVersion": "3.19.0",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "poolName": "iwa.dc",
- "releaseChannel": "BETA"
}
Updates an agent pool update instance settings
agentType | string (AgentType) Agent types that are being monitored |
continueOnError | boolean Continues the update even if some agents fail to update |
latestVersion | string Latest version of the agent |
minimalSupportedVersion | string Minimal version of the agent |
poolName | string Pool name |
releaseChannel | string (ReleaseChannel) Release channel for auto-update |
Updated
Bad Request
Forbidden
Not Found
Too Many Requests
{- "agentType": "AD",
- "continueOnError": true,
- "latestVersion": "3.20.0",
- "minimalSupportedVersion": "3.19.0",
- "poolName": "iwa.dc",
- "releaseChannel": "BETA"
}
{- "agentType": "AD",
- "continueOnError": true,
- "latestVersion": "3.20.0",
- "minimalSupportedVersion": "3.19.0",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "poolName": "iwa.dc",
- "releaseChannel": "BETA"
}
Retrieves an agent pool update by its updateId
OK
Forbidden
Not Found
Too Many Requests
{- "agents": [
- {
- "id": "ajd3fxzltQKQ2VeLu5s6",
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
], - "agentType": "AD",
- "enabled": true,
- "id": "string",
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
Updates an agent pool update instance and returns the latest agent pool update
Array of objects (Agent) | |||||||||||||||||||||
Array
| |||||||||||||||||||||
agentType | string (AgentType) Agent types that are being monitored | ||||||||||||||||||||
enabled | boolean Indicates if auto-update is enabled for the agent pool | ||||||||||||||||||||
name | string Name of the agent pool update | ||||||||||||||||||||
notifyAdmin | boolean Indicates if the admin is notified about the update | ||||||||||||||||||||
reason | string Reason for the update | ||||||||||||||||||||
object (AutoUpdateSchedule) The schedule of auto-update configured by the admin | |||||||||||||||||||||
| |||||||||||||||||||||
sortOrder | integer Specifies the sort order | ||||||||||||||||||||
status | string (AgentUpdateJobStatus) Overall state for the auto-update job from the admin perspective | ||||||||||||||||||||
targetVersion | string The agent version to update to |
Updated
Bad Request
Forbidden
Not Found
Too Many Requests
{- "agents": [
- {
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0"
}
], - "agentType": "AD",
- "enabled": true,
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0"
}
{- "agents": [
- {
- "id": "ajd3fxzltQKQ2VeLu5s6",
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
], - "agentType": "AD",
- "enabled": true,
- "id": "string",
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
Deletes agent pool update
Deleted
Forbidden
Not Found
Too Many Requests
{- "errorCode": "E0000006",
- "errorSummary": "You do not have permission to perform the requested action",
- "errorLink": "E0000006",
- "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
- "errorCauses": [ ]
}
Activates a scheduled agent pool update
Activated
Forbidden
Not Found
Too Many Requests
{- "agents": [
- {
- "id": "ajd3fxzltQKQ2VeLu5s6",
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
], - "agentType": "AD",
- "enabled": true,
- "id": "string",
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
Deactivates scheduled agent pool update
Deactivated
Forbidden
Not Found
Too Many Requests
{- "agents": [
- {
- "id": "ajd3fxzltQKQ2VeLu5s6",
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
], - "agentType": "AD",
- "enabled": true,
- "id": "string",
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
Pauses a running or queued agent pool update
Paused
Forbidden
Not Found
Too Many Requests
{- "agents": [
- {
- "id": "ajd3fxzltQKQ2VeLu5s6",
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
], - "agentType": "AD",
- "enabled": true,
- "id": "string",
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
Resumes a running or queued agent pool update
Resumed
Forbidden
Not Found
Too Many Requests
{- "agents": [
- {
- "id": "ajd3fxzltQKQ2VeLu5s6",
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
], - "agentType": "AD",
- "enabled": true,
- "id": "string",
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
Retries an agent pool update if the update is unsuccessful or communication with Okta was interrupted during an agent auto-update
Retried
Forbidden
Not Found
Too Many Requests
{- "agents": [
- {
- "id": "ajd3fxzltQKQ2VeLu5s6",
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
], - "agentType": "AD",
- "enabled": true,
- "id": "string",
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
Stops an agent pool update
Stopped
Forbidden
Not Found
Too Many Requests
{- "agents": [
- {
- "id": "ajd3fxzltQKQ2VeLu5s6",
- "isHidden": true,
- "isLatestGAedVersion": true,
- "lastConnection": "2019-08-24T14:15:22Z",
- "name": "WIN-region1A-dc",
- "operationalStatus": "DEGRADED",
- "poolId": "0oa3eu7ekG8tjbD9J5s6",
- "type": "AD",
- "updateMessage": "Queued for update.",
- "updateStatus": "Cancelled",
- "version": "3.19.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}
], - "agentType": "AD",
- "enabled": true,
- "id": "string",
- "name": "region1A.dc",
- "notifyAdmin": true,
- "reason": "Update failed.",
- "schedule": {
- "cron": "0 8 ? * 6#3",
- "delay": 0,
- "duration": 120,
- "lastUpdated": "2019-08-24T14:15:22Z",
- "timezone": "America/New_York"
}, - "sortOrder": 0,
- "status": "Cancelled",
- "targetVersion": "3.20.0",
- "_links": {
- "self": {
- "hints": {
- "allow": [
- "DELETE"
]
}, - "href": "string",
- "name": "string",
- "templated": true,
- "type": "string"
}
}
}