Tenable Shared Collections API
The Shared Collections API from Tenable — 5 operation(s) for shared collections.
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Shared Collections 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: Shared Collections
x-displayName: Shared Collections
paths:
/shared-collections:
post:
summary: Create shared collection
description: "Creates a shared collection. You can create up to 1,000 total shared collections. \n\nThis request creates an asynchronous job in Tenable Vulnerability Management. You can query the status of the job with the [Get job status](ref:shared-collections-job-status) endpoint. <div class=\"perms-callout\">Requires the Scan Operator [24] user role or the `VM.VM_SCAN.VM_SCAN_SHARED_COLLECTION.CREATE` custom role privilege. See [Roles](doc:roles).</div>"
operationId: shared-collections-create
tags:
- Shared Collections
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_request-create-shared-collection'
responses:
'200':
description: Returned if the asynchronous job was queued successfully. You can query the status of the job with the [Get job status](ref:shared-collections-job-status) endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_async-api-response-body'
examples:
response:
value:
message: Request has been received.
request_status_id: e0ab9f07-dd4e-4891-9eed-01b47db5ead6
'400':
description: "Returned if your request specified invalid parameters or if your request was improperly formatted. For example: \n- Missing `name` parameter or `acl` object. \n- The `name` or `description` parameters exceed the character limit. \n- The specified `name` already exists.\n- Trying to assign more than one permission to the same user. \n- The `acl` object is missing the `type` property or more than one `OWNER` permission is specified. \n- Trying to assign the `OWNER` permission to a `GROUP` type. \n- Invalid `acl.permission`, `acl.type`, or `acl.uuid`."
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to create a shared collection.
'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/Shared_Collections_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:
- Shared_Collections_cloud: []
get:
summary: List shared collections
description: Returns a list of shared collections that the current user has access to. <div class="perms-callout">Requires the Basic [16] user role or the `VM.VM_SCAN.VM_SCAN_SHARED_COLLECTION.READ` custom role privilege. See [Roles](doc:roles).</div>
operationId: shared-collections-list
tags:
- Shared Collections
responses:
'200':
description: Returned if the list of shared collections was retrieved successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Shared_Collections_shared-collection-object'
examples:
response:
value:
- name: Example Shared Collection
description: An example shared collection.
uuid: 07e3ea92-d792-4d70-b23d-d3d57c63495e
acl:
- permission: OWNER
uuid: f0625cad-6af5-450b-9429-f40419a26189
name: user1@example.com
type: USER
- permission: CAN_EDIT
uuid: 7f46340d-17cc-4760-b170-9fd0954f03e0
name: user2@example.com
type: USER
- permission: CAN_VIEW
uuid: 77935353-13a9-44a6-a098-81cddc4f6250
name: user3@example.com
type: USER
- permission: CAN_VIEW
uuid: cffe9496-4ebc-40e0-ba37-cb0a7dccf34e
name: user4@example.com
type: USER
- permission: CAN_EDIT
uuid: c50df8da-de4f-4c3a-9fc5-09d2f35d7e3f
name: Manager Group
type: GROUP
- permission: CAN_VIEW
uuid: 1b461842-7db5-4d96-9565-8c45b9cf9849
name: Dev Group
type: GROUP
- name: Office Network
description: A shared collection for office scans.
uuid: e01b7836-1e33-42ca-af8e-aa770c01d192
acl:
- permission: OWNER
uuid: 7f46340d-17cc-4760-b170-9fd0954f03e0
name: admin@example.com
type: USER
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to retrieve the list of shared collections.
'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/Shared_Collections_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:
- Shared_Collections_cloud: []
/shared-collections/{shared_collection_id}:
get:
summary: Get shared collection details
description: Returns the details for the specified shared collection. <div class="perms-callout">Requires the Basic [16] user role and the `CAN_VIEW` shared collections permission. Alternatively, requires the `VM.VM_SCAN.VM_SCAN_SHARED_COLLECTION.READ` custom role privilege. See [Roles](doc:roles) and [Permissions](doc:permissions).</div>
operationId: shared-collections-details
tags:
- Shared Collections
parameters:
- name: shared_collection_id
in: path
required: true
description: The `uuid` of the shared collection to return details for.
schema:
type: string
format: uuid
responses:
'200':
description: Returned if the details for the specified shared collection were retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_shared-collection-object'
examples:
response:
value:
name: Office Shared Collection
description: Shared collection for office users.
uuid: ef5b2b45-7d23-46af-a5ce-ca784acb6007
acl:
- permission: OWNER
uuid: 7f46340d-17cc-4760-b170-9fd0954f03e0
name: user@example.com
type: USER
- permission: CAN_VIEW
uuid: 00000000-0000-0000-0000-000000000000
name: All Users
type: GROUP
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to retrieve the shared collection.
'404':
description: Returned if Tenable Vulnerability Management could not find the specified shared collection.
content:
application/json:
examples:
response:
value:
error: No shared collection found with uuid=f5751411-308d-4c56-b85e-48829707c5f3
'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/Shared_Collections_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:
- Shared_Collections_cloud: []
put:
summary: Update shared collection
description: "Updates a shared collection. A shared collection can only be updated by the current owner or an administrator. \n\nThis request creates an asynchronous job in Tenable Vulnerability Management. You can query the status of the job with the [Get job status](ref:shared-collections-job-status) endpoint.\n\n**Note:** To remove a user or group from a shared collection, update the permission to `REMOVE_USER`. <div class=\"perms-callout\">Requires the Scan Operator [24] user role and the `CAN_EDIT` shared collections permission. Alternatively, requires the `VM.VM_SCAN.VM_SCAN_SHARED_COLLECTION.EDIT` custom role privilege. See [Roles](doc:roles) and [Permissions](doc:permissions).</div>"
operationId: shared-collections-update
tags:
- Shared Collections
parameters:
- name: shared_collection_id
in: path
required: true
description: The `uuid` of the shared collection to update.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_request-update-shared-collection'
examples:
response:
value:
message: Request has been received.
request_status_id: de4283db-06c2-4b55-86bb-5f2173bc81b2
responses:
'200':
description: Returned if the asynchronous job was queued successfully. You can query the status of the job with the [Get job status](ref:shared-collections-job-status) endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_async-api-response-body'
examples:
response:
value:
message: Request has been received.
request_status_id: e0ab9f07-dd4e-4891-9eed-01b47db5ead6
'400':
description: "Returned if your request specified invalid parameters or if your request was improperly formatted. For example: \n- Missing `name` parameter or `acl` object. \n- The `name` or `description` parameters exceed the character limit. \n- The specified `name` already exists.\n- Trying to assign more than one permission to the same user. \n- The `acl` object is missing the `type` property or more than one `OWNER` permission is specified. \n- Trying to assign the `OWNER` permission to a `GROUP` type. \n- Invalid `acl.permission`, `acl.type`, or `acl.uuid`."
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to update the shared collection.
'404':
description: Returned if Tenable Vulnerability Management could not find the specified shared collection.
content:
application/json:
examples:
response:
value:
error: No shared collection found with uuid=f5751411-308d-4c56-b85e-48829707c5f3
'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/Shared_Collections_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:
- Shared_Collections_cloud: []
delete:
summary: Delete shared collection
description: "Deletes a shared collection. \n\nThis request creates an asynchronous job in Tenable Vulnerability Management. You can query the status of the job with the [Get job status](ref:shared-collections-job-status) endpoint. <div class=\"perms-callout\">Requires the Administrator [64] user role, the `OWNER` shared collections permission, or the `VM.VM_SCAN.VM_SCAN_SHARED_COLLECTION.DELETE` custom role privilege. See [Roles](doc:roles) and [Permissions](doc:permissions).</div>"
operationId: shared-collections-delete
tags:
- Shared Collections
parameters:
- name: shared_collection_id
in: path
required: true
description: The `uuid` of the shared collection to delete.
schema:
type: string
format: uuid
responses:
'200':
description: Returned if the asynchronous job was queued successfully. You can query the status of the job with the [Get job status](ref:shared-collections-job-status) endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_async-api-response-body'
examples:
response:
value:
message: Request has been received.
request_status_id: de4283db-06c2-4b55-86bb-5f2173bc81b2
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to delete the shared collection.
'404':
description: Returned if Tenable Vulnerability Management could not find the specified shared collection.
content:
application/json:
examples:
response:
value:
error: No shared collection found with uuid=f5751411-308d-4c56-b85e-48829707c5f3
'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/Shared_Collections_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:
- Shared_Collections_cloud: []
/shared-collections/_byName:
post:
summary: Get shared collection details by name
description: Returns the details for the specified shared collection by name. <div class="perms-callout">Requires the Basic [16] user role and the `CAN_VEW` shared collections permission. Alternatively, requires the `VM.VM_SCAN.VM_SCAN_SHARED_COLLECTION.READ` custom role privilege. See [Roles](doc:roles) and [Permissions](doc:permissions).</div>
operationId: shared-collections-details-by-name
tags:
- Shared Collections
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the shared collection to return details for.
example: My Shared Collection
responses:
'200':
description: Returned if the specified shared collection was retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_shared-collection-object'
examples:
response:
value:
name: Office Shared Collection
description: Shared collection for office users.
uuid: ef5b2b45-7d23-46af-a5ce-ca784acb6007
acl:
- permission: OWNER
uuid: 7f46340d-17cc-4760-b170-9fd0954f03e0
name: user@example.com
type: USER
- permission: CAN_VIEW
uuid: 00000000-0000-0000-0000-000000000000
name: All Users
type: GROUP
'400':
description: Returned if your request is missing `name` or if the `name` exceeds the maximum 100 character limit.
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'404':
description: Returned if Tenable Vulnerability Management could not find the specified shared collection.
content:
application/json:
examples:
response:
value:
error: No shared collection found with name=Office
'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/Shared_Collections_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:
- Shared_Collections_cloud: []
/shared-collections/request-status/{request_status_id}:
get:
summary: Get job status
description: "Retrieves the status of the specified asynchronous shared collections job. \n\nYou can use the `request_status_id` returned in the response of the following endpoints to check the status of the asynchronous job: \n- [Create shared collection](ref:shared-collections-create) \n- [Update shared collection](ref:shared-collections-update) \n- [Delete shared collection](ref:shared-collections-delete) \n- [Add scan configs to shared collection](ref:shared-collections-config-add) \n- [Remove scan configs from shared collection](ref:shared-collections-configs-remove) \n<div class=\"perms-callout\">Requires the Basic [16] user role or the `VM.VM_SCAN.VM_SCAN_SHARED_COLLECTION.READ` custom role privilege. See [Roles](doc:roles).</div>"
operationId: shared-collections-job-status
tags:
- Shared Collections
parameters:
- name: request_status_id
in: path
required: true
description: The `request_status_id` or `id` of the asynchronous job you want to retrieve the status for.
schema:
type: string
format: uuid
responses:
'200':
description: Returned if the status of the asynchronous job was retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_request-status-response-body'
examples:
response:
value:
container_uuid: c050dec4-78a7-4d9a-9905-ab9cb3757766
type: shared-collections
id: e0ab9f07-dd4e-4891-9eed-01b47db5ead6
status: completed
created: 1738350594
modified: 1738350594
expiration: 1738352394
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to retrieve the status of the asynchronous job.
'404':
description: Returned if Tenable Vulnerability Management could not find the specified `request_status_id`.
content:
application/json:
examples:
response:
value:
error: No shared collection found with uuid=f5751411-308d-4c56-b85e-48829707c5f3
'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/Shared_Collections_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:
- Shared_Collections_cloud: []
/shared-collections/{shared_collection_id}/scan-configs:
post:
summary: Add scan configs to shared collection
description: "Adds scan configurations to a shared collection. \n\nThis request creates an asynchronous job in Tenable Vulnerability Management. You can query the status of the job with the [Get job status](ref:shared-collections-job-status) endpoint. <div class=\"perms-callout\">Requires the Scan Operator [24] user role and the `CAN_EDIT` shared collections permission. Alternatively, requires the `VM.VM_SCAN.VM_SCAN_SHARED_COLLECTION.CREATE` custom role privilege. See [Roles](doc:roles) and [Permissions](doc:permissions).</div>"
operationId: shared-collections-config-add
tags:
- Shared Collections
parameters:
- name: shared_collection_id
in: path
required: true
description: The `uuid` of the shared collection to add scan configurations to.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- scan_configs
properties:
scan_configs:
type: array
description: 'The list of scan configuration IDs to add to the shared collection. You can add up to 1,000 scan configurations per request.
**Note:** Remediation scan configurations and Web App Scanning (WAS) scan configurations cannot be added to a shared collection. Users must have at least Can View [16] scan permissions to share a scan configuration.'
items:
type: string
example: f536f82a-a3e2-4911-84cb-72cc0177578a
responses:
'200':
description: Returned if the asynchronous job was queued successfully. You can query the status of the job with the [Get job status](ref:shared-collections-job-status) endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/Shared_Collections_async-api-response-body'
examples:
response:
value:
message: Request has been received.
request_status_id: 311dd641-88e6-4b9e-ae93-693d66dfb463
response - duplicate scan configs:
value:
message: 'Request has been received. The following scan configs were already shared to the collection: template-5bbbd6f7-0a85-5d1f-723c-6bb6781abb9efd2a4d8f86043098, template-4a0e770e-34ae-823e-353c-7429dd0bb2fb9996ac3c7d06b5b3, 379bed2d-f8e3-9c3e-66a9-5fa20a04175df74cb55a4f7f8a23, template-f92cfd73-96ce-98c2-ee12-cdcb1323717053f10f42c9475139.'
request_status_id: 311dd641-88e6-4b9e-ae93-693d66dfb463
'400':
description: Returned if your request specified invalid parameters, if your request was improperly formatted, or if the scan configurations are missing from the request.
content:
application/json:
examples:
response - missing scan configs:
value:
error: Request is missing scan configurations.
response - remediation scans:
value:
error: You cannot add remediation scans to a shared collection.
response - web application scans:
value:
error: You cannot add web application scans to a shared collection.
response - too many scan configs:
value:
error: The request exceeds the maximum limit of 1,000 scan configurations per API call.
response - invalid scan config id:
value:
error: Scan configuration `[uuid]` is invalid.
response - no min permissions for scan config:
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-shared-collections-api-openapi.yml