Tenable Agent Tasks API
The Agent Tasks API from Tenable — 10 operation(s) for agent tasks.
The Agent Tasks API from Tenable — 10 operation(s) for agent tasks.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/tenable-agent-tasks-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.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:
responses:
agent-bulk-operations_bulk-response-403:
description: Returned if you do not have permission to create or interact with a bulk operation task.
agent-bulk-operations_bulk-response-200:
description: Returned if Tenable Vulnerability Management successfully created the bulk operation task.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_task'
examples:
response:
value:
task_id: 7aaae2f3-544d-497f-b0f0-447d03d7cd55
container_uuid: 3cc182bb-b8ba-4025-9e59-9a81b8a64d5a
status: RUNNING
message: Starting...
start_time: 1544032287496
last_update_time: 1544032287501
total_work_units: 3
total_work_units_completed: 0
completion_percentage: 0
agent-bulk-operations_bulk-response-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>"
agent-bulk-operations_bulk-response-404:
description: Returned if Tenable Vulnerability Management could not find the specified agent or agent group.
agent-bulk-operations_bulk-response-status-200:
description: Returned if the bulk operation task status information was successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/agent-bulk-operations_task'
examples:
restart-directive:
value:
task_id: 7aaae2f3-544d-497f-b0f0-447d03d7cd55
container_uuid: 3cc182bb-b8ba-4025-9e59-9a81b8a64d5a
status: COMPLETED
message: 3 items completed, 0 failed.
start_time: 1544032287496
last_update_time: 1544032287521
end_time: 1544032287521
total_work_units: 3
total_work_units_completed: 3
completion_percentage: 100
another-response:
value:
task_id: 7aaae2f3-544d-497f-b0f0-447d03d7cd55
container_uuid: 3cc182bb-b8ba-4025-9e59-9a81b8a64d5a
status: COMPLETED
message: 3 items completed, 0 failed.
start_time: 1544032287496
last_update_time: 1544032287521
end_time: 1544032287521
total_work_units: 3
total_work_units_completed: 3
completion_percentage: 100
agent-bulk-operations_bulk-response-400:
description: Returned if your request message contained an invalid parameter.
schemas:
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`—There was an error completing the task.</li><li>`STALE`—The task has not been updated in a long time.</li></ul>
enum:
- NEW
- RUNNING
- COMPLETED
- FAILED
- STALE
message:
type: string
description: An informative, human-readable message about the state of the task.
start_time:
type: integer
format: int64
description: Start time of the task in unix time milliseconds.
end_time:
type: integer
format: int64
description: End time of the task in unix time milliseconds, if the task is finished.
last_update_time:
type: integer
format: int64
description: Last time progress was made on executing the task in unix time milliseconds.
total_work_units:
type: integer
description: Total amount of work which the task will attempt to complete.
total_work_units_completed:
type: integer
description: Total amount of work that the task has completed.
completion_percentage:
type: integer
description: '`total_work_units_completed` divided by `total_work_units`.'
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_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 numeri
# --- 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