# On-prem
Use the following endpoints to manage on-prem groups and on-prem agents programmatically.
# Quick reference
Type | Resource | Description |
---|---|---|
GET | /api/v2/managed_users/:id/on_prem_groups | List on-prem groups in a customer workspace. |
POST | /api/v2/managed_users/:id/on_prem_groups | Create an on-prem group in a customer workspace. |
GET | /api/v2/managed_users/:id/on_prem_groups/:group_id | Retrieve details about an on-prem group in a customer workspace. |
PUT | /api/v2/managed_users/:id/on_prem_groups/:group_id | Updates an on-prem group in a customer workspace. |
DELETE | /api/v2/managed_users/:id/on_prem_groups/:group_id | Deletes an on-prem group in a customer workspace. |
GET | /api/v2/managed_users/:id/on_prem_groups/:group_id/status | Retrieves status of an on-prem group in a customer workspace. |
GET | /api/v2/managed_users/:id/on_prem_agents | List on-prem agents in a customer workspace. |
POST | /api/v2/managed_users/:id/on_prem_agents | Create an on-prem agent in a customer workspace. |
GET | /api/v2/managed_users/:id/on_prem_agents/:agent_id | Retrieve the details of a specific on-prem agent in a customer workspace using its ID. |
PUT | /api/v2/managed_users/:id/on_prem_agents/:agent_id | Update an on-prem agent in a customer workspace. |
DELETE | /api/v2/managed_users/:id/on_prem_agents/:agent_id | Delete an on-prem agent in a customer workspace. |
GET | /api/v2/managed_users/:id/on_prem_agents/:agent_id/status | Retrieve the status of an on-prem agent in a customer workspace. |
GET | /api/v2/managed_users/:id/on_prem_agents/search | Finds on-prem agents in a customer workspace by common name. |
# List on-prem groups
Retrieves a list of all on-prem groups in a customer workspace.
GET /api/v2/managed_users/:id/on_prem_groups
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
# Sample request
curl -X GET 'https://www.workato.com/api/v2/managed_users/12345/on_prem_groups' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"data": [
{
"id": 2159,
"name": "DevOps Network",
"created_at": "2024-09-25T13:09:31.292-07:00",
"use_managed_connection": true,
"config_version": null,
"in_use": false,
"logs_enabled": false
}
]
}
# Create on-prem group
Creates an on-prem group in a customer workspace.
POST /api/v2/managed_users/:id/on_prem_groups
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
# Payload
Name | Type | Description |
---|---|---|
name | string | The on-prem group name. |
# Sample request
curl -X POST 'https://www.workato.com/api/v2/managed_users/12345/on_prem_groups' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name":"CRM server"
}'
# Sample response
[
{
"id": 16803,
"name": "CRM server",
"created_at": "2017-09-21T01:51:45.954-07:00"
}
]
# Get on-prem group details
Retrieves details about an on-prem group in a customer workspace.
GET /api/v2/managed_users/:id/on_prem_groups/:group_id
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
group_id | integer | On-prem group ID. |
# Sample request
curl -X GET 'https://www.workato.com/api/v2/managed_users/12345/on_prem_groups/16803' \
-H 'Authorization: Bearer <api_token>'
# Sample response
[
{
"id": 16803,
"name": "CRM server",
"created_at": "2017-09-21T01:51:45.954-07:00"
}
]
# Update on-prem group
Updates an on-prem group in a customer workspace.
PUT /api/v2/managed_users/:id/on_prem_groups/:group_id
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
group_id | integer | On-prem group ID. |
# Payload
Name | Type | Description |
---|---|---|
name | string | The on-prem group name. |
# Sample request
curl -X PUT 'https://www.workato.com/api/v2/managed_users/12345/on_prem_groups/16803' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name":"CRM server"
}'
# Sample response
[
{
"id": 16803,
"name": "CRM server",
"created_at": "2017-09-21T01:51:45.954-07:00"
}
]
# Delete on-prem group
Deletes an on-prem group in a customer workspace.
DELETE /api/v2/managed_users/:id/on_prem_groups/:group_id
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
group_id | integer | On-prem group ID. |
# Sample request
curl -X DELETE 'https://www.workato.com/api/v2/managed_users/12345/on_prem_groups/16803' \
-H 'Authorization: Bearer <api_token>'
# Sample response
{
"success": true
}
# Get on-prem group status
Retrieves status of an on-prem group in a customer workspace.
GET /api/v2/managed_users/:id/on_prem_groups/:group_id/status
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
group_id | integer | On-prem group ID. |
# Sample request
curl -X GET 'https://www.workato.com/api/v2/managed_users/12345/on_prem_groups/16803/status' \
-H 'Authorization: Bearer <api_token>'
# Sample response
{
"agent_count": 4,
"active_agent_count": 3,
"profiles": [
{
"name": "CRM-Oracle",
"provider": "oracle",
"type": "Database",
"connections": [
{
"id": 440724,
"name": "Oracle CRM DB"
}
]
}
]
}
# List on-prem agents
Retrieves a list of all on-prem agents in a customer workspace.
GET /api/v2/managed_users/:id/on_prem_agents
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
# Sample request
curl -X GET 'https://www.workato.com/api/v2/managed_users/12345/on_prem_agents' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"data": [
{
"id": 29104,
"name": "Marketing(Cupertino)",
"os": "mac",
"installation_method": null,
"awaiting_setup": true,
"enabled": true,
"last_seen_version": null,
"created_at": "2024-09-25T13:21:43.292-07:00",
"updated_at": "2024-09-25T13:21:43.292-07:00",
"state": "awaiting_setup",
"activated": true,
"cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
"on_prem_group_id": 12345
},
{
"id": 29105,
"name": "Sales(Cupertino)",
"os": "mac",
"installation_method": null,
"awaiting_setup": true,
"enabled": true,
"last_seen_version": null,
"created_at": "2024-09-26T09:15:30.123-07:00",
"updated_at": "2024-09-26T09:15:30.123-07:00",
"state": "awaiting_setup",
"activated": true,
"cn": "e29f4b6d8e1845e299e5c8cfb7f72d4a:45678",
"on_prem_group_id": 12345
}
]
}
# Create on-prem agent
Creates an on-prem agent in a customer workspace.
POST /api/v2/managed_users/:id/on_prem_agents
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
# Payload
Name | Type | Description |
---|---|---|
name | string | The on-prem agent name. |
os | string | The server operating system. |
on_prem_group_id | integer | The on-prem group ID. See List on-prem groups. |
awaiting_setup | boolean optional | true if agent should be created in awaiting setup state. Set to false to skip agent setup and get its status right away. |
# Sample request
curl -X POST 'https://www.workato.com/api/v2/managed_users/12345/on_prem_agents' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "US-west-1",
"os": "windows",
"on_prem_group_id": 50,
"awaiting_setup": false
}'
# Sample response
[
{
"id": 12233,
"on_prem_group_id": 16803,
"name": "primary agent",
"cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
"os": "windows",
"awaiting_setup": false,
"enabled": true
}
]
# Get details about an on-prem agent
Retrieves details about an on-prem agent within a customer workspace using its unique ID.
GET /api/v2/managed_users/:id/on_prem_agents/:agent_id
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
agent_id | number required | The ID of the on-prem agent that you plan to retrieve details about. |
# Sample request
curl -X GET 'https://www.workato.com/api/v2/managed_users/12345/on_prem_agents/29104' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"data": [
{
"id": 29104,
"name": "Marketing(Cupertino)",
"os": "mac",
"installation_method": null,
"awaiting_setup": true,
"enabled": true,
"last_seen_version": null,
"created_at": "2024-09-25T13:21:43.292-07:00",
"updated_at": "2024-09-25T13:21:43.292-07:00",
"state": "awaiting_setup",
"activated": true,
"cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
"on_prem_group_id": 12345
}
]
}
# Update on-prem agent
Updates an on-prem agent in a customer workspace.
PUT /api/v2/managed_users/:id/on_prem_agents/:agent_id
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
agent_id | string | On-prem agent ID. |
# Payload
Name | Type | Description |
---|---|---|
name | string | The on-prem agent name. |
os | string | The server operating system. |
on_prem_group_id | integer | The on-prem group ID. See List on-prem groups. |
# Sample request
curl -X PUT 'https://www.workato.com/api/v2/managed_users/12345/on_prem_agents/12233' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "primary agent",
"os": "windows",
"on_prem_group_id": 16803
}'
# Sample response
[
{
"id": 12233,
"on_prem_group_id": 16803,
"name": "primary agent",
"cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
"os": "windows",
"awaiting_setup": false,
"enabled": true
}
]
# Delete on-prem agent
Deletes an on-prem agent in a customer workspace.
DELETE /api/v2/managed_users/:id/on_prem_agents/:agent_id
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
agent_id | string | On-prem agent ID. |
# Sample response
{
"success": true
}
# Get on-prem agent status
Retrieves the status of an on-prem agent in a customer workspace.
GET /api/v2/managed_users/:id/on_prem_agents/:agent_id/status
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
agent_id | string | On-prem agent ID. |
# Sample request
curl -X GET 'https://www.workato.com/api/v2/managed_users/12345/on_prem_agents/29104/status' \
-H 'Authorization: Bearer <api_token>'
# Sample response
{
"active": true
}
# Search on-prem agents
Finds on-prem agents in a customer workspace by common name.
GET /api/v2/managed_users/:id/on_prem_agents/search
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
cn | string | Common name of on-prem agent. |
# Sample request
curl -X GET 'https://www.workato.com/api/v2/managed_users/12345/on_prem_agents/search?cn=example_cn' \
-H 'Authorization: Bearer <api_token>'
# Sample response
[
{
"id": 12233,
"on_prem_group_id": 16803,
"name": "example_cn",
"cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
"os": "windows",
"awaiting_setup": false,
"enabled": true
}
]
Last updated: 5/1/2025, 5:51:43 PM