Tenable Networks API
The Networks API from Tenable — 6 operation(s) for networks.
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Networks 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: Networks
x-displayName: Networks
paths:
/networks:
post:
summary: Create network
description: "Creates a network object that you associate with scanners and scanner groups. \n\n**Note:** You cannot add AWS assets to network objects. For AWS assets, use the network segmentation provided by AWS instead.<div class=\"perms-callout\">Requires the Scan Manager [40] user role or the `VM.VM_SENSOR.NETWORK.CREATE` custom role privilege. See [Roles](doc:roles).</div>"
operationId: networks-create
tags:
- Networks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: "The name of the network object. This name must be unique within your Tenable Vulnerability Management instance, cannot duplicate the name of a previously deleted network, and cannot be `default`. \n \n**Note:** You can add a maximum of 50,000 network objects to an individual Tenable Vulnerability Management instance."
type: string
description:
description: The description of the network object.
type: string
assets_ttl_days:
description: 'The number of days to wait before assets age out. Assets will be permanently deleted if they are not seen on a scan within the specified number of days.<ul><li>Minimum value: 14</li><li>Maximum value: 365</li></ul> **Warning:** If you enable this option, Tenable Vulnerability Management immediately deletes assets in the specified network that have not been seen for the specified number of days. All asset records and associated vulnerabilities are deleted and cannot be recovered. The deleted assets no longer count towards [your license](https://docs.tenable.com/early-access/tenableio/vulnerabilitymanagement/Content/GettingStarted/Licenses.htm).'
type: integer
required:
- name
example:
name: Area 51
description: classified
assets_ttl_days: 91
responses:
'200':
description: Returned if the network was created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/networks_NetworkObject'
examples:
response:
value:
owner_uuid: 0e67b283-07a4-464c-a5e4-7b42576962fd
created: 1557526802865
modified: 1557526802865
scanner_count: 0
uuid: 42475f11-5e6b-4d6a-a53d-63fe494961df
name: Headquarters
description: Network devices at Columbia, MD location
is_default: false
created_by: 0f403df2-3b35-4339-9f74-1574805de203
modified_by: 0f403df2-3b35-4339-9f74-1574805de203
assets_ttl_days: 91
created_in_seconds: 1557526802
modified_in_seconds: 1557526802
'400':
description: 'Returned if Tenable Vulnerability Management encounters invalid JSON in the request body or if an invalid `assets_ttl_days` value was declared (min: 14, max: 365).'
'401':
description: Returned if Tenable Vulnerability Management cannot authenticate the user account that submitted the request.
'403':
description: Returned if you do not have permission to create network objects.
'409':
description: Returned if a network object with the same name already exists.
'415':
description: Returned if the request payload is in an unsupported format.
'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/networks_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.
'503':
description: Returned if a Tenable Vulnerability Management service is unavailable. Wait a moment, and try your request again.
content:
application/json:
examples:
response:
value:
statusCode: 503
error: Service Unavailable
message: Please wait a moment and try your request again.
security:
- networks_cloud: []
get:
summary: List networks
description: Lists network objects for your organization.<div class="perms-callout">Requires the Scan Manager [40] user role or the `VM.VM_SENSOR.NETWORK.READ` custom role privilege. See [Roles](doc:roles).</div>
operationId: networks-list
tags:
- Networks
parameters:
- description: "A filter condition in the following format: `field:operator:value`. For network objects, you can only filter on the `name` field, using the following operators: \n* eq—The name of the returned network object is equal to the text you specify. \n* neq—The returned list of network objects excludes the network object where the name is equal to the text you specify. \n* match—The returned list includes network objects where the name contains the text you specify at least partially.\n\nYou can specify multiple `f` parameters, separated by ampersand (&) characters. If you specify multiple `f` parameters, use the `ft` parameter to specify how Tenable Vulnerability Management applies the multiple filter conditions."
required: false
name: f
in: query
schema:
type: string
- description: The operator that Tenable Vulnerability Management applies if multiple \`f\` parameters are present. The `OR` operator is the only supported value. If you omit this parameter and multiple `f` parameters are present, Tenable Vulnerability Management applies the `OR` operator by default.
required: false
name: ft
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`.
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:asc` would sort results by the `name` field in ascending order.
required: false
name: sort
in: query
schema:
type: string
- description: Indicates whether Tenable Vulnerability Management includes deleted network objects in the response message. Deleted network objects contain the additional attributes, `deleted` and `deleted_by`, which specifies the date (in Unix time) when the network object was deleted and the UUID of the user that deleted the network object.
name: includeDeleted
in: query
schema:
type: boolean
responses:
'200':
description: Returned if the list of networks was retrieved successfully.
content:
application/json:
schema:
type: object
properties:
networks:
type: array
items:
$ref: '#/components/schemas/networks_NetworkObject'
pagination:
type: array
items:
$ref: '#/components/schemas/networks_PaginationResponse'
examples:
response:
value:
networks:
- owner_uuid: ddbd3e11-3311-4682-9912-8e81805fd8a9
created: 154474408527
modified: 154474408527
scanner_count: 10
uuid: 00000000-0000-0000-0000-000000000000
name: Default
is_default: true
created_by: ddbd3e11-3311-4682-9912-8e81805fd8a9
modified_by: ddbd3e11-3311-4682-9912-8e81805fd8a9
created_in_seconds: 1544744085
modified_in_seconds: 1544744085
- owner_uuid: 0e67b283-07a4-464c-a5e4-7b42576962fd
created: 1557526802865
modified: 1557526802865
scanner_count: 1
uuid: 42475f11-5e6b-4d6a-a53d-63fe494961df
name: Headquarters
description: Network devices at Columbia, MD location
is_default: false
created_by: 0f403df2-3b35-4339-9f74-1574805de203
modified_by: 0f403df2-3b35-4339-9f74-1574805de203
assets_ttl_days: 91
created_in_seconds: 1557526802
modified_in_seconds: 1557526802
pagination:
total: 2
limit: 50
offset: 0
sort:
- name: name
order: asc
'400':
description: Returned if the query parameters in your request were invalid.
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/networks_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have sufficient permissions to list network objects.
'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/networks_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.
'503':
description: Returned if a Tenable Vulnerability Management service is unavailable. Wait a moment, and try your request again.
content:
application/json:
examples:
response:
value:
statusCode: 503
error: Service Unavailable
message: Please wait a moment and try your request again.
security:
- networks_cloud: []
/networks/{network_id}:
get:
summary: Get network details
description: Returns the details of the specified network object.<div class="perms-callout">Requires the Scan Manager [40] user role or the `VM.VM_SENSOR.NETWORK.READ` custom role privilege. See [Roles](doc:roles).</div>
operationId: networks-details
tags:
- Networks
parameters:
- description: The UUID of the network object for which you want to view details.
required: true
name: network_id
in: path
schema:
type: string
responses:
'200':
description: Returns the details of the specified network object.
content:
application/json:
schema:
$ref: '#/components/schemas/networks_NetworkObject'
examples:
response:
value:
owner_uuid: 0e67b283-07a4-464c-a5e4-7b42576962fd
created: 1557526802865
modified: 1557526802865
scanner_count: 0
uuid: 42475f11-5e6b-4d6a-a53d-63fe494961df
name: Headquarters
description: Network devices at Columbia, MD location
is_default: false
created_by: 0f403df2-3b35-4339-9f74-1574805de203
modified_by: 0f403df2-3b35-4339-9f74-1574805de203
assets_ttl_days: 91
created_in_seconds: 1557526802
modified_in_seconds: 1557526802
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/networks_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'404':
description: Returned if Tenable Vulnerability Management cannot find a network object with the specified UUID.
'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/networks_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.
'503':
description: Returned if a Tenable Vulnerability Management service is unavailable. Wait a moment, and try your request again.
content:
application/json:
examples:
response:
value:
statusCode: 503
error: Service Unavailable
message: Please wait a moment and try your request again.
security:
- networks_cloud: []
put:
summary: Update network
description: 'Updates the name or description of a network object.
**Note:** The `name` body parameter is required when updating the specified network with this endpoint. To retrieve the `name`, use the [GET /networks/{network_id}](ref:networks-details) endpoint.<div class="perms-callout">Requires the Scan Manager [40] user role or the `VM.VM_SENSOR.NETWORK.EDIT` custom role privilege. See [Roles](doc:roles).</div>'
operationId: networks-update
tags:
- Networks
parameters:
- description: The UUID of the network object you want to update. You cannot update the default network object.
required: true
name: network_id
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: The new name of the network object. This name must be unique within your Tenable Vulnerability Management instance, cannot duplicate the name of a previously deleted network, and cannot be `default`.
type: string
description:
description: The new description of the network object.
type: string
assets_ttl_days:
description: 'The number of days to wait before assets age out. Assets will be permanently deleted if they are not seen on a scan within the specified number of days.<ul><li>Minimum value: 14</li><li>Maximum value: 365</li></ul> **Warning:** If you enable this option, Tenable Vulnerability Management immediately deletes assets in the specified network that have not been seen for the specified number of days. All asset records and associated vulnerabilities are deleted and cannot be recovered. The deleted assets no longer count towards [your license](https://docs.tenable.com/early-access/tenableio/vulnerabilitymanagement/Content/GettingStarted/Licenses.htm).'
type: integer
required:
- name
responses:
'200':
description: Returns successfully updated details of the network object.
content:
application/json:
schema:
$ref: '#/components/schemas/networks_NetworkObject'
examples:
response:
value:
owner_uuid: 0e67b283-07a4-464c-a5e4-7b42576962fd
created: 1557526802865
modified: 1557526802865
scanner_count: 0
uuid: 42475f11-5e6b-4d6a-a53d-63fe494961df
name: Columbia office
description: Network devices at Columbia, MD location
is_default: false
created_by: 0f403df2-3b35-4339-9f74-1574805de203
modified_by: 0f403df2-3b35-4339-9f74-1574805de203
assets_ttl_days: 91
created_in_seconds: 1557526802
modified_in_seconds: 1557526802
'400':
description: 'Returned if Tenable Vulnerability Management encounters invalid JSON in the request body, if you attempted to change the default network object, or if an invalid `assets_ttl_days` value was declared (min: 14, max: 365).'
'401':
description: Returned if Tenable Vulnerability Management cannot authenticate the user account that submitted the request.
'403':
description: Returned if you do not have permission to update the specified network object.
'404':
description: Returned if Tenable Vulnerability Management could not find the specified network object, either because the object does not exist or because the object has been deleted.
'409':
description: Returned if a network object with the same name already exists.
'415':
description: Returned if the request payload is in an unsupported format.
'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/networks_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.
'503':
description: Returned if a Tenable Vulnerability Management service is unavailable. Wait a moment, and try your request again.
content:
application/json:
examples:
response:
value:
statusCode: 503
error: Service Unavailable
message: Please wait a moment and try your request again.
security:
- networks_cloud: []
delete:
summary: Delete network
description: "Deletes the specified network object. Before you delete a network object, consider moving assets to a different network using the bulk asset move endpoint ([POST /api/v2/assets/bulk-jobs/move-to-network](ref:assets-bulk-move)). If you delete a network object, Tenable Vulnerability Management:\n - Returns the scanners and scanner groups associated with the deleted object to the default network object.\n - Retains any asset records for the deleted network until the assets age out of your licensed assets count. \n\n**Note:** You can view deleted network objects using the `includeDeleted` filter in a [GET /networks](ref:networks-list) request. <div class=\"perms-callout\">Requires the Scan Manager [40] user role or the `VM.VM_SENSOR.NETWORK.DELETE` custom role privilege. See [Roles](doc:roles).</div>"
operationId: networks-delete
tags:
- Networks
parameters:
- description: UUID for the network object you want to delete. You cannot delete the default network object.
required: true
name: network_id
in: path
schema:
type: string
responses:
'200':
description: Returned if the specified network object was deleted successfully.
content:
application/json:
schema: {}
examples:
response:
value: {}
'400':
description: Returned if you attempted to delete the default network object.
'401':
description: Returned if Tenable Vulnerability Management cannot authenticate the user account that submitted the request.
'403':
description: Returned if you do not have sufficient permissions to delete the specified network object.
'404':
description: Returned if Tenable Vulnerability Management could not find the network object you specified.
'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/networks_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.
'503':
description: Returned if a Tenable Vulnerability Management service is unavailable. Wait a moment, and try your request again.
content:
application/json:
examples:
response:
value:
statusCode: 503
error: Service Unavailable
message: Please wait a moment and try your request again.
security:
- networks_cloud: []
/networks/{network_id}/counts/assets-not-seen-in/{num_days}:
get:
summary: Get network asset count
description: Returns the total number of assets in the network along with the number of assets that have not been seen for the specified number of days.<p>Requires the Scan Manager [40] user role or `VM.VM_SENSOR.NETWORK.READ` custom role privilege.</p>
operationId: io-networks-asset-count-details
tags:
- Networks
parameters:
- description: The UUID of the network object for which you want to view details.
required: true
name: network_id
in: path
schema:
type: string
- description: 'Return a count of assets that have not been seen for the specified number of days.<ul><li>Minimum value: 1</li><li>Maximum value: 365</li></ul> '
required: true
name: num_days
in: path
schema:
type: integer
responses:
'200':
description: Returns the total number of assets in the network along with the number of assets that have not been seen for the specified number of days.
content:
application/json:
schema:
$ref: '#/components/schemas/networks_NetworkAssetCount'
examples:
response:
value:
numAssetsNotSeen: 200
numAssetsTotal: 1000
'400':
description: 'Returned if the parameters in your request were invalid. For example, if `num_days` is out of range (min: 1, max: 365).'
content:
application/json:
examples:
response:
value:
statusCode: 400
error: Bad Request
message: child "days" fails because ["days" must be less than or equal to 365]
validation:
source: params
keys:
- days
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/networks_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'404':
description: Returned if Tenable Vulnerability Management cannot find a network object with the specified UUID.
'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/networks_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.
'503':
description: Returned if a Tenable Vulnerability Management service is unavailable. Wait a moment, and try your request again.
content:
application/json:
examples:
response:
value:
statusCode: 503
error: Service Unavailable
message: Please wait a moment and try your request again.
security:
- networks_cloud: []
/networks/{network_id}/scanners/{scanner_uuid}:
post:
summary: Assign scanners
description: 'Associates a scanner or scanner group with a network object. Use this endpoint to:<ul><li>Assign a scanner or scanner group to a custom network object.</li><li>Return a scanner or scanner group to the default network object.</li></ul><div class="perms-callout">Requires the Scan Manager [40] user role or one of the following custom role privileges: `VM.VM_SENSOR.VM_SCANNER.EDIT`, `VM.VM_SENSOR.VM_WAS_SCANNER.EDIT`, or `VM.VM_SENSOR.VM_NETWORK_MONITOR.EDIT`. See [Roles](doc:roles).</div>'
operationId: networks-assign-scanner
tags:
- Networks
parameters:
- description: The UUID of the network object where you want to assign a scanner or scanner group.
required: true
name: network_id
in: path
schema:
type: string
- description: The UUID of the scanner or scanner group you want to assign to the network object. To get UUID values, use the [GET /networks/{network_id}/assignable-scanners](ref:networks-list-assignable-scanners) endpoint.
required: true
name: scanner_uuid
in: path
schema:
type: string
responses:
'200':
description: Returned if the scanner or scanner group to the network object was assigned successfully.
content:
application/json:
schema: {}
examples:
response:
value: {}
'400':
description: Returned if you attempt to assign an AWS scanner to the network object. For AWS assets, use network segmentation processes offered by AWS instead.
'401':
description: Returned if Tenable Vulnerability Management cannot authenticate the user account that submitted the request.
'403':
description: Returned if you do not have sufficient permissions to assign a scanner or scan
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-networks-api-openapi.yml