# 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/21/2025, 5:22:32 AM