Tenable Scan Status API

openapi: 3.0.0
info:
  version: 1.0.0
  title: Downloads About Scan Status 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: Scan Status
  x-displayName: Scan Status
paths:
  /scans/{scan_id}/latest-status:
    get:
      summary: Get latest scan status
      description: Returns the latest status for a scan. For a list of possible status values, see [Scan Status](doc:scan-status-tio).<div class="perms-callout">Requires the Scan Operator [24] user role and Can View [16] scan permissions. See [Roles](doc:roles) and [Permissions](doc:permissions).</div>
      operationId: scans-get-latest-status
      tags:
      - Scan Status
      parameters:
      - description: The unique identifier for the scan.  This identifier can be either the `scans.schedule_uuid` or the `scans.id` attribute in the response message from the [GET /scans](ref:scans-list) endpoint. Tenable recommends that you use `scans.schedule_uuid`.
        required: true
        name: scan_id
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Returned if the scan status was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The latest status of the scan. For a list of possible status values, see [Scan Status](doc:scan-status-tio).
              examples:
                response:
                  value:
                    status: imported
        '401':
          description: Returned if the API keys specified in your request are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan_Status_ErrorResponse'
              examples:
                response:
                  value:
                    statusCode: 401
                    error: Unauthorized
                    message: Invalid credentials.
        '404':
          description: Returned if Tenable Vulnerability Management cannot find the specified scan.
          content:
            application/json:
              schema:
                type: object
                description: Error message
                properties:
                  error:
                    type: string
                    description: A brief description of the cause of the error.
              examples:
                response:
                  value:
                    info:
                      error: The requested file was not found
        '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/Scan_Status_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:
      - Scan_Status_cloud: []
  /scans/{scan_id}/status:
    put:
      summary: Update scan status
      description: Changes the status of a scan. For a list of possible status values, see [Scan Status](doc:scan-status-tio).<div class="perms-callout">Requires the Scan Operator [24] user role and Can View [16] scan permissions. See [Roles](doc:roles) and [Permissions](doc:permissions).</div>
      operationId: scans-read-status
      tags:
      - Scan Status
      parameters:
      - description: The unique identifier for the scan. This identifier can be either the `scans.schedule_uuid` or the `scans.id` attribute in the response message from the [GET /scans](ref:scans-list) endpoint. Tenable recommends that you use `scans.schedule_uuid`.
        required: true
        name: scan_id
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                read:
                  type: boolean
                  description: If `true`, the scan has been read.
              required:
              - read
      responses:
        '200':
          description: Returned if the scan status was updated successfully.
          content:
            application/json:
              schema: {}
              examples:
                response:
                  value: {}
        '401':
          description: Returned if the API keys specified in your request are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan_Status_ErrorResponse'
              examples:
                response:
                  value:
                    statusCode: 401
                    error: Unauthorized
                    message: Invalid credentials.
        '404':
          description: Returned if Tenable Vulnerability Management cannot find the specified scan.
        '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/Scan_Status_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:
      - Scan_Status_cloud: []
  /scans/{scan_id}/progress:
    get:
      summary: Get scan progress
      description: 'Returns the progress for the specified scan.


        **Note:** If you submit a request without query parameters, Tenable Vulnerability Management returns the progress from the latest run of the specified scan. If you submit a request using the `history_id` or `history_uuid` query parameters to specify a historical run of the scan, Tenable Vulnerability Management returns the progress for the specified historical run.<div class="perms-callout">Requires the Scan Operator [24] user role and Can View [16] scan permissions. See [Roles](doc:roles) and [Permissions](doc:permissions).</div>'
      operationId: io-vm-scans-progress-get
      tags:
      - Scan Status
      parameters:
      - description: 'The unique identifier of the scan you want to retrieve the progress for.


          For the identifier, you can use either the `scans.schedule_uuid` or the `scans.id` attribute from the [GET /scans](ref:scans-list) endpoint. However, Tenable recommends that you use `scans.schedule_uuid`.'
        required: true
        name: scan_id
        in: path
        schema:
          type: string
      - description: 'The unique identifier of the historical run of the scan that you want to retrieve the progress for.


          This identifier corresponds to the `history.id` attribute from the [GET /scans/{scan_id}/history](ref:scans-history) endpoint. You can use either this parameter or the `history_uuid` query parameter to specify a historical run of the scan.'
        name: history_id
        in: query
        schema:
          type: integer
          format: int32
      - description: 'The UUID of the historical run of the scan that you want to retrieve the progress for.


          This identifier corresponds to the `history.scan_uuid` attribute from the [GET /scans/{scan_id}/history](ref:scans-history) endpoint. You can use either this parameter or the `history_id` query parameter to specify a historical run of the scan.'
        name: history_uuid
        in: query
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Returned if the scan progress for the specified scan or historical run of the scan was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  progress:
                    type: integer
                    description: The progress of the scan ranging from 0 to 100.
              examples:
                response:
                  value:
                    progress: 50
        '401':
          description: Returned if the API keys specified in your request are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan_Status_ErrorResponse'
              examples:
                response:
                  value:
                    statusCode: 401
                    error: Unauthorized
                    message: Invalid credentials.
        '404':
          description: Returned if Tenable Vulnerability Management cannot find the specified scan.
          content:
            application/json:
              schema:
                type: object
                description: Error message
                properties:
                  error:
                    type: string
                    description: A brief description of the cause of the error.
              examples:
                response:
                  value:
                    info:
                      error: The requested file was not found
        '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/Scan_Status_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:
      - Scan_Status_cloud: []
components:
  schemas:
    Scan_Status_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.
  securitySchemes:
    Bearer:
      type: apiKey
      in: header
      name: Authorization
      description: 'Example: Bearer {{token}}'
x-readme:
  proxy-enabled: false
  explorer-enabled: true
  samples-enabled: true
  samples-languages:
  - python
  - curl
  - node
  - powershell
  - ruby
  - javascript
  - objectivec
  - java
  - php
  - csharp
  - go
  - swift
  - kotlin