Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Developer API
Resources

On-premise API ​

Workato API allows you to work with on-prem groups and on-prem agents through the API.

Rate limits ​

On-prem resources have the following rate limits:

TypeResourceQuota
AllAll On-prem endpoints60 requests per minute

Quick reference ​

TypeResourceDescription
GET/api/on_prem_groupsList on-prem groups.
POST/api/on_prem_groupsCreate on-prem group.
GET/api/on_prem_groups/:idGet on-prem group details.
PUT/api/on_prem_groups/:idUpdate on-prem group.
DELETE/api/on_prem_groups/:idDelete an on-prem group.
GET/api/on_prem_groups/:id/statusGet on-prem group status.
GET/api/on_prem_agentsList on-prem agents.
POST/api/on_prem_agentsCreate on-prem agent.
GET/api/on_prem_agents/:idGet on-prem agent details.
PUT/api/on_prem_agents/:idUpdate on-prem agent.
DELETE/api/on_prem_agents/:idDelete on-prem agents.
GET/api/on_prem_agents/:id/statusGet on-prem agent status.
GET/api/on_prem_agents/searchSearch for on-prem agent.
GET/api/on_prem_agents/:id/activation_codeGet on-prem agent activation code.

List on-prem groups ​

List all on-prem groups in your workspace.

GET https://YOUR_DATA_CENTER/api/on_prem_groups

Sample request ​

shell
curl -X GET 'https://YOUR_DATA_CENTER/api/on_prem_groups' \
     -H 'Authorization: Bearer <api_token>' \

Response ​

json
[
  {
    "id": 16803,
    "name": "CRM server",
    "created_at": "2017-09-21T01:51:45.954-07:00",
    "in_use": true,
    "use_managed_connection": true,
    "config_version": 9,
    "logs_enabled": false,
    "whitelisted_ips": [
      "198.51.100.10",
      "192.0.2.0/24"
    ]
  }
]

Create on-prem group ​

Create an on-prem group.

POST https://YOUR_DATA_CENTER/api/on_prem_groups

Payload ​

NameTypeDescription
namestring
required		The on-prem group's name.
use_managed_connectionboolean
optional		Set to true to configure the on-prem group using a cloud profile or false to configure each agent manually using a config.yml file. Defaults to false if not specified.
settings_attributes[whitelisted_ips]array of strings
optional		Defines IPs to whitelist for the on-prem group.

Sample request ​

shell
curl -X POST 'https://YOUR_DATA_CENTER/api/on_prem_groups' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "name": ":name",
          "use_managed_connection": :true_or_false,
          "settings_attributes": {
            "whitelisted_ips": [
              ":whitelisted_ip_1",
              ":whitelisted_ip_2"
            ]
          }
         }'

Response ​

json
{
  "id": 16803,
  "name": "CRM server",
  "created_at": "2017-09-21T01:51:45.954-07:00",
  "in_use": false,
  "use_managed_connection": true,
  "config_version": null,
  "logs_enabled": false,
  "whitelisted_ips": [
    "198.51.100.10",
    "192.0.2.0/24"
  ]
}

Get on-prem group details ​

Get details about an on-prem group.

GET https://YOUR_DATA_CENTER/api/on_prem_groups/:id

URL parameters ​

NameTypeDescription
idinteger
required		The ID of the on-prem group to retrieve.

Sample request ​

shell
curl -X GET 'https://YOUR_DATA_CENTER/api/on_prem_groups/:id' \
     -H 'Authorization: Bearer <api_token>' \

Response ​

json
{
  "id": 16803,
  "name": "CRM server",
  "created_at": "2017-09-21T01:51:45.954-07:00",
  "in_use": false,
  "use_managed_connection": false,
  "config_version": null,
  "logs_enabled": false,
  "whitelisted_ips": [
      "198.51.100.10",
      "192.0.2.0/24"
  ]
}

Update on-prem group ​

Update an on-prem group.

PUT https://YOUR_DATA_CENTER/api/on_prem_groups/:id

URL parameters ​

NameTypeDescription
idinteger
required		The on-prem group's ID.

Payload ​

NameTypeDescription
namestring
optional		The on-prem group's name.
settings_attributes[whitelisted_ips]array of strings
optional		Defines IPs to whitelist for the on-prem group.

Sample request ​

shell
curl -X PUT 'https://YOUR_DATA_CENTER/api/on_prem_groups/:id' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "name": ":name",
          "settings_attributes": {
            "whitelisted_ips": [
              ":whitelisted_ip_1",
              ":whitelisted_ip_2"
            ]
          }
         }'

Response ​

json
{
  "id": 16803,
  "name": "CRM server",
  "created_at": "2017-09-21T01:51:45.954-07:00",
  "in_use": false,
  "use_managed_connection": false,
  "config_version": null,
  "logs_enabled": false,
  "whitelisted_ips": [
    "198.51.100.10",
    "192.0.2.0/24"
  ]
}

Delete on-prem group ​

Delete an on-prem group and the on-prem agents it contains.

DELETE https://YOUR_DATA_CENTER/api/on_prem_groups/:id

URL parameters ​

NameTypeDescription
idinteger
required		The on-prem group's ID.

Sample request ​

shell
curl -X DELETE 'https://YOUR_DATA_CENTER/api/on_prem_groups/:id' \
     -H 'Authorization: Bearer <api_token>' \

Response ​

json
{
  "success": true
}

Get on-prem group status ​

Get the status of an on-prem group.

GET https://YOUR_DATA_CENTER/api/on_prem_groups/:id/status

URL parameters ​

NameTypeDescription
idinteger
required		The on-prem group's ID.

Sample request ​

shell
curl -X GET 'https://YOUR_DATA_CENTER/api/on_prem_groups/:id/status' \
     -H 'Authorization: Bearer <api_token>' \

Response ​

json
{
  "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 ​

List all on-prem agents in your workspace.

GET https://YOUR_DATA_CENTER/api/on_prem_agents

Sample request ​

shell
curl -X GET 'https://YOUR_DATA_CENTER/api/on_prem_agents' \
     -H 'Authorization: Bearer <api_token>' \

Response ​

json
[
  {
    "id": 12233,
    "on_prem_group_id": 16803,
    "name": "primary agent",
    "cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
    "os": "windows",
    "installation_method": null,
    "awaiting_setup": false,
    "enabled": true,
    "last_seen_version": "25.0",
    "created_at": "2024-12-10T13:20:03.330-08:00",
    "updated_at": "2025-05-12T13:03:23.754-07:00",
    "state": "connected",
    "activated": true
  }
]

Create on-prem agent ​

Create an on-prem agent.

POST https://YOUR_DATA_CENTER/api/on_prem_agents

Payload ​

NameTypeDescription
namestring
required		The on-prem agent's name.
on_prem_group_idinteger
required		The on-prem group's ID. You can retrieve group IDs from the List on-prem groups endpoint's response.
osstring
optional		The server's operating system.
awaiting_setupboolean
optional		Set to true to create the agent in the awaiting_setup state. Set to false to skip agent setup and get its status right away. Defaults to true if not specified.
enabledboolean
optional		Set to true to enable the agent or false to disable it.

Sample request ​

shell
curl -X POST 'https://YOUR_DATA_CENTER/api/on_prem_agents' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "name": ":name",
          "on_prem_group_id": :on_prem_group_id_value,
          "os": ":os",
          "awaiting_setup": :true_or_false
         }'

Response ​

json
{
  "id": 12233,
  "on_prem_group_id": 50,
  "name": "US-west-1",
  "cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
  "os": "windows",
  "installation_method": null,
  "awaiting_setup": false,
  "enabled": true,
  "last_seen_version": null,
  "created_at": "2025-06-24T12:37:49.824-07:00",
  "updated_at": "2025-06-24T12:37:49.886-07:00",
  "state": "connected",
  "activated": false
}

Get on-prem agent details ​

Get the details of an on-prem agent.

GET https://YOUR_DATA_CENTER/api/on_prem_agents/:id

URL parameters ​

NameTypeDescription
idinteger
required		The on-prem agent's ID.

Sample request ​

shell
curl -X GET 'https://YOUR_DATA_CENTER/api/on_prem_agents/:id' \
     -H 'Authorization: Bearer <api_token>' \

Response ​

json
{
  "id": 12233,
  "on_prem_group_id": 16803,
  "name": "primary agent",
  "cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
  "os": "windows",
  "installation_method": null,
  "awaiting_setup": true,
  "enabled": true,
  "last_seen_version": null,
  "created_at": "2025-06-24T12:37:49.824-07:00",
  "updated_at": "2025-06-24T12:37:49.886-07:00",
  "state": "awaiting_setup",
  "activated": false
}

Update on-prem agent ​

Update an on-prem agent.

PUT https://YOUR_DATA_CENTER/api/on_prem_agents/:id

URL parameters ​

NameTypeDescription
idinteger
required		The on-prem agent's ID.

Payload ​

NameTypeDescription
namestring
optional		The on-prem agent's name.
osstring
optional		The server's operating system.
on_prem_group_idinteger
optional		The on-prem group's ID. You can retrieve group IDs from the List on-prem groups endpoint's response.
enabledboolean
optional		Set to true to enable the agent or false to disable it.

Sample request ​

shell
curl -X PUT 'https://YOUR_DATA_CENTER/api/on_prem_agents/:id' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": ":name"
         }'

Response ​

json
{
  "id": 49026,
  "on_prem_group_id": 32109,
  "name": "primary agent",
  "cn": "1ee944db3b24d7c19dfe4685c49b77a4:49026",
  "os": "windows",
  "installation_method": null,
  "awaiting_setup": false,
  "enabled": true,
  "last_seen_version": "27.0",
  "created_at": "2025-03-27T08:18:49.641-07:00",
  "updated_at": "2025-05-12T13:26:36.731-07:00",
  "state": "connected",
  "activated": true
}

Delete on-prem agent ​

Delete an on-prem agent.

DELETE https://YOUR_DATA_CENTER/api/on_prem_agents/:id

URL parameters ​

NameTypeDescription
idinteger
required		The on-prem agent's ID.

Sample request ​

shell
curl -X DELETE 'https://YOUR_DATA_CENTER/api/on_prem_agents/:id' \
     -H 'Authorization: Bearer <api_token>' \

Response ​

json
{
  "success": true
}

Get on-prem agent status ​

Get the status of an on-prem agent.

GET https://YOUR_DATA_CENTER/api/on_prem_agents/:id/status

URL parameters ​

NameTypeDescription
idinteger
required		The on-prem agent's ID.

Sample request ​

shell
curl -X GET 'https://YOUR_DATA_CENTER/api/on_prem_agents/:id/status' \
     -H 'Authorization: Bearer <api_token>' \

Response ​

json
{
  "active": true
}

Search for on-prem agent by common name ​

Search on-prem agents by their common name.

GET https://YOUR_DATA_CENTER/api/on_prem_agents/search

URL parameters ​

NameTypeDescription
cnstring
optional		The common name of the on-prem agent to retrieve. Omit this parameter to return all agents.

Sample request ​

shell
curl -X GET 'https://YOUR_DATA_CENTER/api/on_prem_agents/search' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d  '{
             "cn": "134fd7acd89cf5b8b96deea4870d413d:12233"
          }'

Response ​

json
[
  {
    "id": 12233,
    "on_prem_group_id": 16803,
    "name": "primary agent",
    "cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
    "os": "windows",
    "awaiting_setup": false,
    "enabled": true
  }
]

Get on-prem agent activation code ​

Get an activation code for an on-prem agent.

GET https://YOUR_DATA_CENTER/api/on_prem_agents/:id/activation_code

URL parameters ​

NameTypeDescription
idinteger
required		The on-prem agent's ID.

Sample request ​

shell
curl -X GET 'https://YOUR_DATA_CENTER/api/on_prem_agents/:id/activation_code' \
     -H 'Authorization: Bearer <api_token>' \

Response ​

json
[
  {
    "code": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiMjY3MTA4NTU5NDBmMGFjYTVmNDYyMTFhNWYxMmJiNzo2MDg3MCIsImlhdCI6MTc0ODcyNTU5OSwiZXhwIjoxNzQ4NzI5MTk5LCJhZ2VudCI6NjA4NzAsImd3Ijoic2czLndvcmthdG8uY29tfHNnNC53b3JrYXRvLmNvbSJ9.JCcQ0NCetvIjP9xJJ1BIUAxmE9ImuNvtUJLNIazICiQg61RlSz2YJHywhbSXvakjjB77L7ZPydo43Rs_iiWiWRr5atk8iHvZlnfAKL_338-nFxmSkN-Ms7sL-fguNdQaO-DgkkZubAJ-qP8a34VKJ6QYA3c3SaixoNfnukKan0mUySTz7wQsVxU4C0Ff0R42AGO9CjKxYRobeBr_QgLJm6PtSUN5J6JkWGpyg9jTHJEpsFPDLBzJ0u7O7HkDP_onF4wdrraJ7_5BSn04ZllXw6oIwTbMWq1ncqhYHs0ZXNnv3efXF4L0tzgSkekdz-YasqojNSo0wzfpV0W_3vq_Mg"
  }
]

Last updated: