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:

Type Resource Limit
AllAll On-prem endpoints60 requests per minute

# Quick reference

Type Resource Description
GET /api/on_prem_groups List on-prem groups.
POST /api/on_prem_groups Create on-prem group.
GET /api/on_prem_groups/:id Get on-prem group details.
PUT /api/on_prem_groups/:id Update on-prem group.
DELETE /api/on_prem_groups/:id Delete an on-prem group.
GET /api/on_prem_groups/:id/status Get on-prem group status.
GET /api/on_prem_agents List on-prem agents.
POST /api/on_prem_agents Create on-prem agent.
GET /api/on_prem_agents/:id Get on-prem agent details.
PUT /api/on_prem_agents/:id Update on-prem agent.
DELETE /api/on_prem_agents/:id Delete on-prem agents.
GET /api/on_prem_agents/:id/status Get on-prem agent status.
GET /api/on_prem_agents/search Search for on-prem agent.
GET /api/on_prem_agents/:id/activation_code Get on-prem agent activation code.

# List on-prem groups

List all on-prem groups in your workspace.

GET /api/on_prem_groups

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_groups' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "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 /api/on_prem_groups

# Payload

Name Type Description
name string
required		 The on-prem group's name.
use_managed_connection boolean
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

curl -X POST 'https://www.workato.com/api/on_prem_groups' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "name":"CRM server",
          "use_managed_connection": true,
          "settings_attributes": { 
            "whitelisted_ips": [
              "198.51.100.10",
              "192.0.2.0/24"
            ]
          }
         }'

# Response

[
  {
    "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 /api/on_prem_groups/:id

# URL parameters

Name Type Description
id integer
required		 The ID of the on-prem group to retrieve.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_groups/16803' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "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 /api/on_prem_groups/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem group's ID.

# Payload

Name Type Description
name string
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

curl -X PUT 'https://www.workato.com/api/on_prem_groups/16803' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "name":"CRM server",
          "settings_attributes": { 
            "whitelisted_ips": [
              "198.51.100.10",
              "192.0.2.0/24"
            ]
          }
         }'

# Response

[
  {
    "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 /api/on_prem_groups/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem group's ID.

# Sample request

curl -X DELETE 'https://www.workato.com/api/on_prem_groups/16803' \
     -H 'Authorization: Bearer <api_token>' \

# Response

{
  "success": true
}

# Get on-prem group status

Get the status of an on-prem group.

GET /api/on_prem_groups/:id/status

# URL parameters

Name Type Description
id integer
required		 The on-prem group's ID.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_groups/16805/status' \
     -H 'Authorization: Bearer <api_token>' \

# 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

List all on-prem agents in your workspace.

GET /api/on_prem_agents

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_agents' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "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 /api/on_prem_agents

# Payload

Name Type Description
name string
required		 The on-prem agent's name.
on_prem_group_id integer
required		 The on-prem group's ID. You can retrieve group IDs from the List on-prem groups endpoint's response.
os string
optional		 The server's operating system.
awaiting_setup boolean
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.

# Sample request

curl -X POST 'https://www.workato.com/api/on_prem_agents' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "name": "US-west-1",
          "on_prem_group_id": 50,
          "os": "windows",
          "awaiting_setup": false
         }'

# Response

[
  {
    "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 /api/on_prem_agents/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_agents/12233' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "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 /api/on_prem_agents/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Payload

Name Type Description
name string
optional		 The on-prem agent's name.
os string
optional		 The server's operating system.
on_prem_group_id integer
optional		 The on-prem group's ID. You can retrieve group IDs from the List on-prem groups endpoint's response.

# Sample request

curl -X POST 'https://www.workato.com/api/on_prem_agents/49026' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "primary agent"
         }'

# Response

[
  {
    "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 /api/on_prem_agents/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Sample request

curl -X DELETE 'https://www.workato.com/api/on_prem_agents/12233' \
     -H 'Authorization: Bearer <api_token>' \

# Response

{
  "success": true
}

# Get on-prem agent status

Get the status of an on-prem agent.

GET /api/on_prem_agents/:id/status

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_agents/12233/status' \
     -H 'Authorization: Bearer <api_token>' \

# Response

{
  "active": true
}

# Search for on-prem agent by common name

Search on-prem agents by their common name.

GET /api/on_prem_agents/search

# URL parameters

Name Type Description
cn string
optional		 The common name of the on-prem agent to retrieve. Omit this parameter to return all agents.

# Sample request

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

# Response

[
  {
    "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 /api/on_prem_agents/:id/activation_code

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_agents/12233/activation_code' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "code": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiMjY3MTA4NTU5NDBmMGFjYTVmNDYyMTFhNWYxMmJiNzo2MDg3MCIsImlhdCI6MTc0ODcyNTU5OSwiZXhwIjoxNzQ4NzI5MTk5LCJhZ2VudCI6NjA4NzAsImd3Ijoic2czLndvcmthdG8uY29tfHNnNC53b3JrYXRvLmNvbSJ9.JCcQ0NCetvIjP9xJJ1BIUAxmE9ImuNvtUJLNIazICiQg61RlSz2YJHywhbSXvakjjB77L7ZPydo43Rs_iiWiWRr5atk8iHvZlnfAKL_338-nFxmSkN-Ms7sL-fguNdQaO-DgkkZubAJ-qP8a34VKJ6QYA3c3SaixoNfnukKan0mUySTz7wQsVxU4C0Ff0R42AGO9CjKxYRobeBr_QgLJm6PtSUN5J6JkWGpyg9jTHJEpsFPDLBzJ0u7O7HkDP_onF4wdrraJ7_5BSn04ZllXw6oIwTbMWq1ncqhYHs0ZXNnv3efXF4L0tzgSkekdz-YasqojNSo0wzfpV0W_3vq_Mg"
  }
]
← Delete a row
Projects →


Last updated: 8/5/2025, 10:05:03 PM

On this page