Tenable Agents API
The Agents API from Tenable — 4 operation(s) for agents.
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Agents API
description: 'The Downloads API enables customers to access and download installation and update files for available Tenable products. You can use the API endpoints to list product pages, list downloads available for a specific product, and to download a file. The endpoints can also be used to determine and download the latest version of a file to facilitate the automation of an installation.
**Note:** The Tenable Downloads API uses a different server URL than the Tenable Vulnerability Management API:
`https://www.tenable.com/downloads/api/v2/pages`.
### Authentication
Like the Downloads website, certain files require authentication to download. When files have a `"requires_auth": true` attribute on the product list page, the Downloads API uses bearer token authentication and requires a valid token in the Authorization header to download the file:
```
Authorization: Bearer AbCdEf123456
```
To access or reset your authentication token, navigate to the [Authentication Token](https://www.tenable.com/downloads/api-docs) page.
Examples of product downloads that **do not** require authentication include Nessus and Nessus Agents.'
servers:
- url: https://www.tenable.com/downloads/api/v2
security:
- Bearer: []
tags:
- name: Agents
x-displayName: Agents
paths:
/scanners/null/agents:
get:
summary: List agents
description: Returns a list of agents for the specified scanner.<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: agents-list
tags:
- Agents
parameters:
- description: "Apply a filter in the format `::`. For example, `field1:match:sometext` would match any records where the value of field1 contains `sometext`. You can use multiple query filters. \n\nUse the [List agent filters](ref:io-filters-agents-list) endpoint to retrieve the list of supported filters, including their valid operators and value types."
required: false
name: f
in: query
schema:
type: string
- description: Filter type. If the filter type is `and`, the record is only returned if all filters match. If the filter type is `or`, the record is returned if any of the filters match.
required: false
name: ft
in: query
schema:
type: string
- description: Wildcard filter text. Wildcard search is a mechanism where multiple fields of a record are filtered against one specific filter string. If any one of the wildcard\_fields' values matches against the filter string, then the record matches the wildcard filter. For a record to be returned, it must pass the wildcard filter (if there is one) AND the set of standard filters. For example, if `w=wild&f=field1:match:one&f=field2:match:two&ft=or`, the record would match if the value of any supported wildcard\_fields contained `wild`, AND either field1's value contained `one` or field2's value contained `two`.
required: false
name: w
in: query
schema:
type: string
- description: A comma-delimited subset of wildcard\_fields to search when applying the wildcard filter. For example, `field1,field2`. If `w` is provided, but `wf` is not, then all wildcard\_fields' values are searched against the wildcard filter text.
required: false
name: wf
in: query
schema:
type: string
- description: The number of records to retrieve. If this parameter is omitted, Tenable Vulnerability Management uses the default value of `50`. The minimum supported limit is `1`, and the maximum supported limit is `5000`.
required: false
name: limit
in: query
schema:
type: integer
format: int32
- description: The starting record to retrieve. If this parameter is omitted, Tenable Vulnerability Management uses the default value of `0`.
required: false
name: offset
in: query
schema:
type: integer
format: int32
- description: 'The field you want to use to sort the results by along with the sort order. The field is specified first, followed by a colon, and the order is specified second (`asc` or `desc`). For example, `name:desc` would sort results by the `name` field in descending order.
If you specify multiple fields, the fields must be separated by commas. For example, `name:desc,platform:asc` would first sort results by the `name` field in descending order and then by the `platform` field in ascending order.
Sort can only be applied to the sortable_fields specified by the filter capabilities. There may be no more than max_sort_fields number of columns used in the sort, as specified by the filter capabilities.'
required: false
name: sort
in: query
schema:
type: string
responses:
'200':
description: Returned if the list of agents was retrieved successfully.
content:
application/json:
schema:
type: object
properties:
agents:
type: array
items:
$ref: '#/components/schemas/agents_response-list-agents'
pagination:
$ref: '#/components/schemas/agents_PaginationResponse'
examples:
response:
value:
agents:
- id: 9176838
uuid: 655993d5-c131-46e8-a82f-957f6f894cac
name: GRD-LPTP
platform: WINDOWS
distro: win-x86-64
ip: 192.0.2.57
core_version: 7.0.0
linked_on: 1456775443
last_connect: 1515674073
status: 'off'
groups:
- name: North America Agents
id: 8
- name: Windows Agents
id: 3316
supports_remote_logs: false
network_uuid: 00000000-0000-0000-0000-000000000000
network_name: Default
profile_uuid: 00000000-0000-0000-0000-000000000000
profile_name: Default
supports_remote_settings: true
asset_uuid: bb1a9cf3-55a2-54ea-c88e-9a15000452f2
health: 0
health_state_name: HEALTHY
safe_mode: 0
last_safe_mode: 1740070459626
fredi_status: true
runtime_scanning_health: -1
nessus_scanning_health: 0
- id: 14569
uuid: 72ac6ad1-fc86-4af4-be0c-0ff3bfbfb242
name: example.com
platform: LINUX
distro: es7-x86-64
ip: 192.0.2.57
core_version: 7.0.3
linked_on: 1508329832
last_connect: 1526565530
status: 'off'
groups:
- name: SC Research
id: 1167
asset_uuid: da1a9cf3-33a2-45ae-b99d-9a15000451e1
health: 10
health_state_name: WARNING
safe_mode: 0
last_safe_mode: 1740070459626
fredi_status: true
runtime_scanning_health: -1
nessus_scanning_health: 0
- id: 14570
uuid: 938cb466-06ea-477e-abb0-99d8da0e0f20
name: example.com
platform: LINUX
distro: es7-x86-64
ip: 192.0.2.57
core_version: 7.0.3
linked_on: 1508329886
last_connect: 1526565624
status: 'off'
groups:
- name: AWS agents
id: 1167
aws_public_ipv4: 203.0.113.17
aws_public_hostname: ec2-203-0-113-42.compute-1.amazonaws.com
aws_instance_id: i-0123456789abcdef0
aws_account_id: '123456789012'
asset_uuid: b23a9cf3-23a2-45ab-b99d-9a15000451c5
health: 20
health_state_name: CRITICAL
safe_mode: 0
last_safe_mode: 1740070459626
fredi_status: true
runtime_scanning_health: -1
nessus_scanning_health: 0
pagination:
total: 3
limit: 50
offset: 0
sort:
- name: name
order: asc
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: A brief description of the cause of the error.
examples:
response:
value:
error: Bad value for date filter
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agents_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to view the list of agents.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agents_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- agents_cloud: []
/scanners/null/agent-groups/{agent_group_id}/agents:
get:
summary: List agents by group
description: Returns a list of agents for the specified agent group.<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: agent-group-list-agents
tags:
- Agents
parameters:
- description: The ID of the agent group to query for agents. You can find the ID by using the [GET /scanners/{scanner_id}/agent-groups](ref:agent-groups-list) endpoint.
required: true
name: agent_group_id
in: path
schema:
type: integer
format: int32
- description: "Apply a filter in the format `::`. For example, `field1:match:sometext` would match any records where the value of field1 contains `sometext`. You can use multiple query filters. \n\nUse the [List agent filters](ref:io-filters-agents-list) endpoint to retrieve the list of supported filters, including their valid operators and value types."
required: false
name: f
in: query
schema:
type: string
- description: Filter type. If the filter type is `and`, the record is only returned if all filters match. If the filter type is `or`, the record is returned if any of the filters match.
required: false
name: ft
in: query
schema:
type: string
- description: Wildcard filter text. Wildcard search is a mechanism where multiple fields of a record are filtered against one specific filter string. If any one of the wildcard\_fields' values matches against the filter string, then the record matches the wildcard filter. For a record to be returned, it must pass the wildcard filter (if there is one) AND the set of standard filters. For example, if `w=wild&f=field1:match:one&f=field2:match:two&ft=or`, the record would match if the value of any supported wildcard\_fields contained `wild`, AND either field1's value contained `one` or field2's value contained `two`.
required: false
name: w
in: query
schema:
type: string
- description: A comma-delimited subset of wildcard\_fields to search when applying the wildcard filter. For example, `field1,field2`. If `w` is provided, but `wf` is not, then all wildcard\_fields' values are searched against the wildcard filter text.
required: false
name: wf
in: query
schema:
type: string
- description: The number of records to retrieve. If this parameter is omitted, Tenable Vulnerability Management uses the default value of `50`. The minimum supported limit is `1`, and the maximum supported limit is `5000`.
required: false
name: limit
in: query
schema:
type: integer
format: int32
- description: The starting record to retrieve. If this parameter is omitted, Tenable Vulnerability Management uses the default value of `0`.
required: false
name: offset
in: query
schema:
type: integer
format: int32
- description: 'The field you want to use to sort the results by along with the sort order. The field is specified first, followed by a colon, and the order is specified second (`asc` or `desc`). For example, `name:desc` would sort results by the `name` field in descending order.
If you specify multiple fields, the fields must be separated by commas. For example, `name:desc,platform:asc` would first sort results by the `name` field in descending order and then by the `platform` field in ascending order.
Sort can only be applied to the sortable_fields specified by the filter capabilities. There may be no more than max_sort_fields number of columns used in the sort, as specified by the filter capabilities.'
required: false
name: sort
in: query
schema:
type: string
responses:
'200':
description: Returned if the list of agents was retrieved successfully.
content:
application/json:
schema:
type: object
properties:
agents:
type: array
items:
$ref: '#/components/schemas/agents_response-list-agents'
pagination:
$ref: '#/components/schemas/agents_PaginationResponse'
examples:
response:
value:
agents:
- id: 20
uuid: 96efbd47-9d96-443f-be29-2ac723dde270
name: MD-MacBook-Pro.local
platform: DARWIN
distro: macosx
ip: 10.31.100.110
last_scanned: 1545272687
plugin_feed_id: '201812281741'
core_build: '1'
core_version: 7.2.1
linked_on: 1452106253
last_connect: 1546264939
status: 'off'
groups:
- name: MacOS Agents
id: 8
- name: North America Agents
id: 31
- name: Bi-weekly Scan Agents
id: 3315
supports_remote_logs: false
asset_uuid: 5d1a9cf3-33a2-45ae-b99d-9a15000451e1
health: 0
health_state_name: HEALTHY
safe_mode: 0
last_safe_mode: 1740070459626
fredi_status: false
runtime_scanning_health: -1
nessus_scanning_health: 0
- id: 65
uuid: 7d14d098-2c60-403a-a1d0-8bce78e27f867b06b5e32a5e47a1
name: DC02
platform: WINDOWS
distro: win-x86-64
ip: 10.31.114.10
last_scanned: 1478743235
plugin_feed_id: '0'
linked_on: 1453821446
status: 'off'
groups:
- name: Agent Group A
id: 8
- name: Agent Group B
id: 31
- name: Agent Group C
id: 3316
supports_remote_logs: false
asset_uuid: ba4a9cf3-33a2-45ae-b99d-9a1500045345
health: 0
health_state_name: HEALTHY
safe_mode: 0
last_safe_mode: 1740070459626
fredi_status: false
runtime_scanning_health: -1
nessus_scanning_health: 0
- id: 643
uuid: d59d1f5b-f775-4061-9e36-fae22ab7518f2596d192e3cf57f8
name: DESKTOP-PSNDJQ6
platform: WINDOWS
distro: win-x86-64
ip: 192.0.2.3
last_scanned: 1477011651
plugin_feed_id: '0'
linked_on: 1468619962
status: 'off'
groups:
- name: Agent Group A
id: 8
- name: Agent Group C
id: 3316
aws_public_ipv4: 203.0.113.17
aws_public_hostname: ec2-203-0-113-42.compute-1.amazonaws.com
aws_instance_id: i-0123456789abcdef0
aws_account_id: '123456789012'
supports_remote_logs: false
asset_uuid: 321a9cf3-33a2-45ae-b99d-9a1500045444
health: 0
health_state_name: HEALTHY
safe_mode: 0
last_safe_mode: 1740070459626
fredi_status: false
runtime_scanning_health: -1
nessus_scanning_health: 0
pagination:
total: 3
limit: 50
offset: 0
sort:
- name: name
order: asc
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: A brief description of the cause of the error.
examples:
response:
value:
error: Bad value for date filter
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agents_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to view the list of agents.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agents_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- agents_cloud: []
/agents/safe-mode-summary:
get:
summary: Get agent safe mode summary
description: "Returns a summary of agents in safe mode for your container. The summary includes the total number of agents along with breakdowns by agent version and operating system platform. \n\n**Note:** Agent safe mode is supported by agent version 10.9.0 and later. \n\nFor more information about agent safe mode, see [Agent Safe Mode](https://docs.tenable.com/vulnerability-management/Content/Settings/Sensors/agent-safe-mode.htm) in the _Tenable Vulnerability Management User Guide_ and [Safe Mode](https://docs.tenable.com/nessus-agent/Content/safe-mode.htm) in the _Tenable Agent User Guide_. <div class=\"perms-callout\">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>"
operationId: agents-get-safe-mode-summary
tags:
- Agents
responses:
'200':
description: Returned if the agent safe mode summary was retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/agents_safe-mode-summary'
examples:
response:
value:
container_uuid: 270f4c4c-4c4c-4c4c-4c4c-be827c004c4c
user_uuid: 4a5e4c4c-4c4c-4c4c-4c4c-0f1f1994c4c
site: na-accounts
agent_safe_mode_count:
total: 16
by_version:
10.8.3: 16
by_platform:
DARWIN: 8
WINDOWS: 8
time_stamp: 1741794158635
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agents_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to view the agent safe mode summary.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agents_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- agents_cloud: []
/scanners/null/agents/{agent_id}:
get:
summary: Get agent details
description: Returns the specified agent details for the specified scanner.<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: agents-get
tags:
- Agents
parameters:
- description: The ID of the agent to query.
required: true
name: agent_id
in: path
schema:
type: integer
format: int32
responses:
'200':
description: Returned if the specified agent's details were retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/agents_response-agent-details'
examples:
response:
value:
id: 643
uuid: d59d1f5b-f775-4061-9e36-fae22ab7518f2596d192e3cf57f8
name: DESKTOP-PSNDJQ6
platform: WINDOWS
distro: win-x86-64
ip: 192.0.2.57
last_scanned: 1477011651
plugin_feed_id: '0'
linked_on: 1468619962
status: 'off'
groups:
- name: North America Agents
id: 8
- name: Windows Agents
id: 3316
aws_public_ipv4: 203.0.113.17
aws_public_hostname: ec2-203-0-113-42.compute-1.amazonaws.com
aws_instance_id: i-0123456789abcdef0
aws_account_id: '123456789012'
supports_remote_logs: false
network_uuid: 00000000-0000-0000-0000-000000000000
network_name: Default
profile_uuid: 00000000-0000-0000-0000-000000000000
profile_name: Default
remote_settings:
- name: Nessus Agent Log Level
setting: backend_log_level
type: select
description: This controls the Nessus Agent backend logging level. Backend reload required.
backend_reload: true
status: current
value: verbose
allowable_values:
- value: verbose
- value: debug
- value: normal
default: normal
- name: Plugin Compilation Performance
setting: plugin_load_performance_mode
type: select
description: Controls the performance for plugin compilation; lower performance takes longer to compile, but uses fewer system processor resources. Service restart required. Requires 8.1.0+
service_restart: true
status: current
value: high
allowable_values:
- value: high
- value: medium
- value: low
default: high
- name: Scan Performance
setting: scan_performance_mode
type: select
description: Controls the scan performance; lower performance takes longer to scan, but uses fewer system processor resources. Service restart required. Requires 8.1.0+
service_restart: true
status: current
value: high
allowable_values:
- value: high
- value: medium
- value: low
default: high
- name: Nessus Agent Update Plan
setting: agent_update_channel
type: select
description: The update plan to which Nessus Agent will track. Requires 7.7.0+
status: current
value: ga
allowable_values:
- value: ga
label: Keep up to date with GA releases.
- value: ea
label: Opt in to Early Access releases.
- value: stable
label: Delay updates, staying on the last stable release.
default: ga
- name: Automatic Hostname Update
setting: update_hostname
type: boolean
description: If the Nessus Agent's hostname is changed, the new hostname is updated in the Nessus Agent's manager.
status: current
value: 'false'
default: 'false'
- name: Offline Agent Scan Trigger Execution Threshold
setting: offline_agent_scan_trigger_execution_threshold_days
type: integer
description: Specifies the number of days of the Agent being offline after which Rule-Based Scans will stop executing
min: 1
status: current
value: '14'
default: '14'
- name: Maximum Scans Per Day
setting: maximum_scans_per_day
type: integer
description: The maximum number of scans to run on this Agent per day.
min: 1
max: 48
status: current
value: '10'
default: '10'
- name: Minimum Health Update Interval
setting: min_agent_health_update_interval
type: integer
description: Specifies, in minutes, the minimum interval to update health events
min: 60
status: current
value: '60'
default: '60'
supports_remote_settings: true
restart_pending: false
asset_uuid: 3c1a9cf3-33a2-45ae-b99d-9a1500045d4f
health: 0
health_state_name: HEALTHY
health_events:
- identifier: 201
state: 0
state_time: 1722960875000
details: Plugin update was successful.
muted: false
state_name: HEALTHY
identifier_name: PLUGIN_UPDATE
- identifier: 200
state: 0
state_time: 1722960320000
details: Nessus Agent plugin disk usage is normal.
muted: false
state_name: HEALTHY
identifier_name: PLUGIN_DISK_USAGE
safe_mode: 2
last_safe_mode: 1740070459310
fredi_status: false
runtime_scanning_health: -1
nessus_scanning_health: 0
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-agents-api-openapi.yml