Tenable Agent Tasks API
The Agent Tasks API from Tenable — 10 operation(s) for agent tasks.
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Agent Tasks 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: Agent Tasks
x-displayName: Agent Tasks
paths:
/scanners/null/agents/_bulk/{task_uuid}:
get:
summary: Get agent task status
description: "Returns the status of the specified asynchronous bulk agent task. \n\nUse the `task_id` value returned by supported endpoints to track the progress or completion of the asynchronous task.<div class=\"perms-callout\">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>"
operationId: bulk-task-agent-status
tags:
- Agent Tasks
parameters:
- description: The unique identifier (UUID) of the task.
required: true
name: task_uuid
in: path
schema:
type: string
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-status-200'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
/scanners/null/agent-groups/{group_id}/agents/_bulk/{task_uuid}:
get:
summary: Check agent group operation status
description: Check the status of a bulk operation on an agent group.<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: bulk-task-agent-group-status
tags:
- Agent Tasks
parameters:
- description: The ID or UUID of the agent group.
required: true
name: group_id
in: path
schema:
type: integer
format: int32
- description: The UUID of the task.
required: true
name: task_uuid
in: path
schema:
type: string
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-status-200'
'400':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-400'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
/scanners/null/agent-groups/{group_id}/agents/_bulk/add:
post:
summary: Add agents to a group
description: Creates a bulk operation task to add agents to a group.<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: bulk-add-agents
tags:
- Agent Tasks
parameters:
- description: The ID or UUID of the agent group.
required: true
name: group_id
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_bulk-filter'
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-200'
'400':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-400'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
/scanners/null/agent-groups/{group_id}/agents/_bulk/remove:
post:
summary: Remove agents from group
description: Creates a bulk operation task to remove agents from a group.<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: bulk-remove-agents
tags:
- Agent Tasks
parameters:
- description: The ID or UUID of the agent group.
required: true
name: group_id
in: path
schema:
type: integer
format: int32
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_bulk-filter'
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-200'
'400':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-400'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
/scanners/null/agents/_bulk/addToNetwork:
post:
summary: Add agents to a network
description: Creates a bulk operation task to add agents to a custom network. <div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: io-agent-bulk-operations-add-to-network
tags:
- Agent Tasks
requestBody:
required: true
content:
application/json:
schema:
allOf:
- type: object
required:
- network_uuid
properties:
network_uuid:
type: string
description: The UUID of the network to add the agents to.
- $ref: '#/components/schemas/agent-bulk-operations_bulk-filter'
example:
criteria:
all_agents: true
not_items:
- 1
- 2
- 3
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-200'
'400':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-400'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
/scanners/null/agents/_bulk/removeFromNetwork:
post:
summary: Remove agents from network
description: 'Creates a bulk operation task to remove agents from a custom network.
**Note:** Agents that are removed from a custom network will be added to the `Default` network.<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>'
operationId: io-agent-bulk-operations-remove-from-network
tags:
- Agent Tasks
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- network_uuid
properties:
network_uuid:
type: string
description: The UUID of the network to remove the agents from.
criteria:
$ref: '#/components/schemas/agent-bulk-operations_bulk-filter-criteria'
items:
type: array
description: An array of agent IDs or agent UUIDs to add to the criteria filter.
items:
oneOf:
- title: String for Agent UUIDs (OPTION 1)
type: string
- title: Integer for Agent IDs (OPTION 2)
type: integer
not_items:
type: array
description: An array of agent IDs or agent UUIDs to exclude from the criteria filter.
items:
oneOf:
- title: String for Agent UUIDs (OPTION 1)
type: string
- title: Integer for Agent IDs (OPTION 2)
type: integer
example:
criteria:
all_agents: true
not_items:
- 1
- 2
- 3
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-200'
'400':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-400'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
/scanners/null/agents/_bulk/assignToProfile:
post:
summary: Assign or remove profile
description: "Assigns or removes agents from a profile by creating an asynchronous bulk operation task. \n\n**Note:** You can create an agent profile using the [Create profile](ref:profiles-create) endpoint.<div class=\"perms-callout\">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>"
operationId: agent-bulk-operations-profile
tags:
- Agent Tasks
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- title: Assign agents to a profile
allOf:
- type: object
required:
- profile_uuid
properties:
profile_uuid:
type: string
format: uuid
description: The unique identifier (UUID) of the agent profile to assign the agents to.
- $ref: '#/components/schemas/agent-bulk-operations_bulk-filter'
- title: Remove agents from a profile
$ref: '#/components/schemas/agent-bulk-operations_bulk-filter'
example:
criteria:
all_agents: true
not_items:
- 1
- 2
- 3
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-200'
'400':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-400'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
/scanners/null/agents/_bulk/directive:
post:
summary: Send instructions to agents
description: Create instructions for agents to perform. Instructions include restarting or changing local product settings.<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: io-agent-bulk-operations-directive
tags:
- Agent Tasks
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_bulk-filter-with-directive'
examples:
restart-directive:
value:
criteria:
all_agents: true
not_items:
- 1234
directive:
type: restart
options:
hard: true
idle: true
settings-directive:
value:
criteria:
all_agents: true
not_items:
- 1234
directive:
type: settings
options:
settings:
- value: debug
setting: backend_log_level
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-200'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'404':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-404'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
/scanners/null/agent-groups/{group_id}/agents/_bulk/directive:
post:
summary: Send instructions to agents group
description: Create instructions for agents in an agent group to perform. Instructions include restarting or changing local product settings.<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: io-agent-bulk-operations-group-directive
tags:
- Agent Tasks
parameters:
- description: The ID or UUID of the agent group.
required: true
name: group_id
in: path
schema:
type: integer
format: int32
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_bulk-filter-with-directive'
examples:
restart-directive:
value:
criteria:
all_agents: true
not_items:
- 1234
directive:
type: restart
options:
hard: true
idle: true
settings-directive:
value:
criteria:
all_agents: true
not_items:
- 1234
directive:
type: settings
options:
settings:
- value: debug
setting: backend_log_level
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-200'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'404':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-404'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
/scanners/null/agents/_bulk/unlink:
post:
summary: Unlink agents
description: Creates a bulk operation task to unlink agents. For more information on unlinked agent data, see [Unlink an Agent](https://docs.tenable.com/vulnerability-management/Content/Settings/Sensors/UnlinkAnAgent.htm).<div class="perms-callout">Requires the Scan Manager [40] user role. See [Roles](doc:roles).</div>
operationId: bulk-unlink-agents
tags:
- Agent Tasks
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_bulk-filter'
responses:
'200':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-200'
'400':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-400'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-403'
'429':
$ref: '#/components/responses/agent-bulk-operations_bulk-response-429'
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_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:
- agent-bulk-operations_cloud: []
components:
schemas:
agent-bulk-operations_bulk-filter:
type: object
properties:
criteria:
$ref: '#/components/schemas/agent-bulk-operations_bulk-filter-criteria'
items:
type: array
description: An array of agent IDs or agent UUIDs to add to the criteria filter.
items:
oneOf:
- title: String for Agent UUIDs (OPTION 1)
type: string
- title: Integer for Agent IDs (OPTION 2)
type: integer
not_items:
type: array
description: An array of agent IDs or agent UUIDs to exclude from the criteria filter.
items:
oneOf:
- title: String for Agent UUIDs (OPTION 1)
type: string
- title: Integer for Agent IDs (OPTION 2)
type: integer
example:
criteria:
all_agents: true
not_items:
- 1
- 2
- 3
agent-bulk-operations_ErrorResponse:
type: object
properties:
statusCode:
type: integer
description: The HTTP status code of the error.
error:
type: string
description: The standard HTTP error name.
message:
type: string
description: A brief message about the cause of the error.
agent-bulk-operations_bulk-filter-with-directive:
type: object
properties:
criteria:
$ref: '#/components/schemas/agent-bulk-operations_bulk-filter-criteria'
items:
type: array
description: An array of agent IDs or agent UUIDs to add to the criteria filter.
items:
oneOf:
- title: String for Agent UUIDs (OPTION 1)
type: string
- title: Integer for Agent IDs (OPTION 2)
type: integer
not_items:
type: array
description: An array of agent IDs or agent UUIDs to exclude from the criteria filter.
items:
oneOf:
- title: String for Agent UUIDs (OPTION 1)
type: string
- title: Integer for Agent IDs (OPTION 2)
type: integer
directive:
type: object
description: Specifies the instructions you wish to send to the agents. The `directive` object is different depending on whether you want to restart the agents or change settings for the agents.
oneOf:
- title: Restart Directive (OPTION 1)
properties:
type:
type: string
description: The type of instruction to perform. For restarting agents, the type is always `restart`.
enum:
- restart
options:
type: object
description: The options for the restart operation.
properties:
hard:
type: boolean
description: Indicates whether or not to perform a hard restart. A hard restart will inform the Nessus Agent to restart immediately regardless of what it is doing.
idle:
type: boolean
description: Indicates whether or not to restart when the scanning engine is idle.
- title: Settings Directive (OPTION 2)
properties:
type:
type: string
description: The type of instruction to perform. For modifying settings, the type is always `settings`.
enum:
- settings
options:
type: object
description: The instructions to perform, with a key of `settings`. Please see the examples for more information.
properties:
settings:
type: array
description: An array of objects where each object is one individual instruction to perform where `setting` is the command and `value` is what to change it to. For example, `{"setting":"backend_log_level","value":"debug"}`.
items:
type: object
properties:
setting:
type: string
value:
type: string
agent-bulk-operations_bulk-filter-criteria:
type: object
description: Specifies the criteria you wish to filter agents on. The criteria is used to narrow down the list of agents to perform the specified action on.
properties:
all_agents:
type: boolean
description: Indicates whether or not to match against all agents.
wildcard:
type: string
description: A string used to match against all string-like attributes of an agent.
filters:
type: array
description: 'An array of string or numeric operations to match against agents. For example, `name:match:laptop` or `core_version:lt:10.0.0`.
Use the [List agent filters](ref:io-filters-agents-list) endpoint to retrieve the list of supported filters, including their valid operators and value types.'
items:
type: string
example:
- name:match:laptop
- core_version:lt:10.0.0
filter_type:
type: string
description: Indicates how to combine the `filters` conditions. Possible values are `and` or `or`.
enum:
- and
- or
hardcoded_filters:
type: array
description: 'Additional filters that will always be added as `and` conditions.
Use the [List agent filters](ref:io-filters-agents-list) endpoint to retrieve the list of supported filters, including their valid operators and value types.'
items:
type: string
agent-bulk-operations_task:
type: object
properties:
task_id:
type: string
description: The UUID of the task.
container_uuid:
type: string
description: The UUID of the container where the task is operating.
status:
type: string
description: The status of the task. Possible status values are:<ul><li>`NEW`—The task was created but has not yet started running.</li><li>`RUNNING`—The task is in progress.</li><li>`COMPLETED`—The task is done.</li><li>`FAILED`�
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-agent-tasks-api-openapi.yml