openapi: 3.1.0
info:
  title: InsightAppSec Accounts Scan Engine API
  description: '<p>Welcome to the reference documentation for the public APIs available for InsightAppSec.</p><p>Here are a few resources to help you learn how to start using our APIs:</p><ul><li><a href=''https://insight.help.rapid7.com/docs/api-overview''>Learn about basic concepts and capabilities</a></li><li><a href=''https://insight.help.rapid7.com/docs/managing-platform-api-keys''>Get an Insight platform API key to set up authentication</a></li><li><a href=''https://insight.help.rapid7.com/docs/product-apis''>See available Insight product APIs</a></li><li><a href=''https://insightappsec.help.rapid7.com/docs''>Learn more about InsightAppSec</a></li></ul><p>After you''ve got the basics down, you can use this API guide to find examples of requests and responses.</p></p><h2>Permissions</h2><p>This API uses the platform role of a user''s API key to inherit a set of permissions.</p><p><b>Notes</b>:<li>Platform Admins do not require explicit access to an App in order to see it, or anything associated with it</li><li>Organization keys will inherit Product Admin permissions.</li></p><table><thead><tr><th>Role</th><th>Permissions</th></tr></thead><tbody><tr><td>Product Admin</td><td><li><code>Manage Apps</code></li><li><code>Read Attack Templates</code></li><li><code>Manage Targets</code><li><code>Manage Scan Configs</code><li><code>Manage Scans</code></li><li><code>Manage Vulnerabilities</code></li><li><code>Administer Vulnerability Comments</code></li><li><code>Manage Engines</code></li><li><code>Manage Engine Groups</code></li><li><code>Manage Schedules</code></li><li><code>Manage Blackouts</code></li><li><code>Manage Global Blackouts</code></li><li><code>Manage Files</code></li><li><code>Manage Tags</code></li><li><code>Manage PDF Report</code></li></td></tr><tr><td>Read Write</td><td><li><code>Manage Apps</code></li><li><code>Read Attack Templates</code></li><li><code>Read Targets</code><li><code>Manage Scan Configs</code><li><code>Manage Scans</code></li><li><code>Manage Vulnerabilities</code></li><li><code>Manage Vulnerability Comments</code></li><li><code>Read Engines</code></li><li><code>Read Engine Groups</code></li><li><code>Manage Schedules</code></li><li><code>Manage Blackouts</code></li><li><code>Manage Files</code></li><li><code>Manage Tags</code></li><li><code>Manage PDF Report</code></li></td></tr><tr><td>Read Only</td><td><li><code>Read Apps</code></li><li><code>Read Attack Templates</code></li><li><code>Read Targets</code><li><code>Read Scan Configs</code><li><code>Read Scans</code></li><li><code>Read Vulnerabilities</code></li><li><code>Read Vulnerability Comments</code></li><li><code>Read Engines</code></li><li><code>Read Engine Groups</code></li><li><code>Read Schedules</code></li><li><code>Read Blackouts</code></li><li><code>Read Files</code></li><li><code>Read Tags</code></li><li><code>Read PDF Report</code></li></td></tr></tbody><table><a href="#pagination"><h2 id="pagination">Pagination Parameters</h2></a><p>The following query parameters can be used to control the order, offset and size of the returned data</p><table><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>index</code></td><td><p>The 0-based index of the page of data desired (default: 0)<p></td><td><code>?index=2</code></td></tr><tr><td><code>size</code></td><td><p>The size of the page of data desired (min: 1, max: 1000, default: 50)<p></td><td><code>?size=10</code></td></tr><tr><td><code>sort</code></td><td><p>The sort terms and (optional) directions for the desired ordering of data (default: specific to each resource)<p></td><td><code>?sort=scan.submit_time,DESC,scan.status</code></td></tr><tr><td><code>page-token</code></td><td><p>The page token, used as an alternative to <code>index</code> (default: Not provided)<p></td><td><code>?page-token=NDM0NTk0NTIyOjo6X1M6OjpiYW5hbmFz</code></td></tr></tbody></table><h3>Paging using a page token</h3><p>When intending to page beyond the 10,000th result, or as an alternative to using the <code>index</code> query parameter, the <code>page-token</code> option may be used instead. After retrieving the first page, the <code>page_token</code> will be present in the <code>metadata</code> section of the response.<br />For example, with <code>size=99</code>, <code>index=0</code> to <code>index=99</code> may be used. To load the next page, use the <code>page_token</code> value used in the response e.g. <code>?page-token=NDM0NTk0NTIyO</code> </p><h2>Creating resources</h2><p>As is generally the accepted practice with REST-ful APIs, creating a resource can be performed by sending an appropriately formatted POST request. Any ID provided for a new resource in a POST request <i>body</i> will simply be ignored (and a new one generated internally and returned as part of the resource in subsequent GET requests), and POST requests to URLs following a format similar to <code>.../resource/<ID></code> are unsupported and should respond with <code>415 Method Not Allowed</code>. All requests which successfully create a resource and respond with <code>201 Created</code> will contain a <code>Location</code> header the value of which is an absolute URI for the resource (the ID of which can be determined as the last section of the path in the given URI). For example:<br /><code>Location: https://us.api.insight.rapid7.com/ias/v1/scans/12345678-1234-5678-90AB-1234567890AB</code></p><h2>Date, Time and Timezone Support</h2><p>The value of date and date-time type properties are fixed to the common ISO-8601 format. Unless otherwise specified, all date or date-time data in response bodies are expressed in UTC, and it is also expected that data provided in request bodies are also expressed in UTC.</p><h3>Schedules and Blackouts</h3><p>The <code>first_start</code> and <code>first_end</code> properties of both Blackouts and Schedules, and the <code>last_start</code> property of Blackouts may be specified with a timezone. If the timezone is not specified, it is assumed to be UTC. For example:<br /><code>2019-08-12T14:00:00.000000Z[Asia/Tokyo]</code><br />It is also possible to specify the timezone as an offset of either <code>GMT</code> or <code>UTC</code>. For example:<br /><code>2019-09-04T15:00:00.000000Z[GMT+03:00]</code></p><table><thead><tr><th>Value</th><th>Format</th><th>Notes</th></tr></thead><tbody><tr><td>Date</td><td>YYYY-MM-DD</td><td>Defaults to 12 am UTC (if used for a date &amp; time)</td></tr><tr><td>Date &amp; time only</td><td>YYYY-MM-DD''T''hh:mm:ss[.nnn]</td><td>Defaults to UTC</td></tr><tr><td>Date &amp; time in UTC</td><td>YYYY-MM-DD''T''hh:mm:ss[.nnn]Z</td><td></td></tr><tr><td>Date &amp; time with specific timezone</td><td>YYYY-MM-DD''T''hh:mm:ss[.nnn]Z[TimeZoneId]</td><td></td></tr></tbody></table><h2>Searching and Filtering</h2><p>One characteristic of a powerful API is support for complex search and filtering of resources using a flexible query language. It is entirely possible to provide basic search and filtering functionality on standard GET resource collection operations using HTTP query parameters, but this becomes restrictive when attempting to encode boolean logic. Other solutions are also possible but come with equally restrictive compromises. The most effective way to facilitate this complex search and filtering is to provide it as a top-level API with a robust Domain-Specific Language (DSL).</p><p>For simple data retrieval that supports paging and sorting functionality, use the traditional resource-specific GET collection operations; for more complex data retrieval that supports a user-crafted query DSL, use the global Search operation.</p><h2>Errors</h2><p>Any response from the API with an HTTP Status Code in the 4xx or 5xx range indicates an error. If in the 4xx range it indicates a client-side error, where in the 5xx range it indicates a server-side error. All responses indicating an error should be JSON formatted, and contain both a "status" and a "message" property indicating the cause of the error, a "r7-correlation-id" header should also always be returned in the format of a UUID, which uniquely identifies the HTTP exchange that took place and caused the error (this header is present on <i>every</i> request). On some occasions, an "error_code" property will be included in the response body, which can provide the support team further context into the cause of the error in cases where the message is not explicitly clear.</p><p>When contacting support about error responses received from the API, please attempt to include, at minimum:<ul><li>A description of the requests intent</li><li>The request URL</li><li>The request body</li><li>The error response body</li><li>The error response "r7-correlation-id" header</li></ul></p><h3>Validation Errors</h3><p>Specifically, when a response with an HTTP Status Code of 422 is returned, this indicates a validation error, almost always received in a response from a non-idempotent request (normally PUT, POST or DELETE). In this case, there should be an additional "errors" property included in the JSON response body that should describe the cause of the validation exception; this will almost always require a modification to the request body to resolve. </p>'
  version: v1
servers:
- url: https://[region].api.insight.rapid7.com/ias/v1
tags:
- name: Scan Engine
  description: Resources and operations for managing scan engines.
paths:
  /api/3/scan_engine_pools:
    get:
      tags:
      - Scan Engine
      summary: Engine Pools
      description: Returns engine pools available to use for scanning.
      operationId: getScanEnginePools
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters: []
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Resources«EnginePool»'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    post:
      tags:
      - Scan Engine
      summary: Engine Pools
      description: Creates a new engine pool.
      operationId: createScanEnginePool
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - in: body
        name: enginePool
        description: The details for the scan engine to update.
        required: false
        schema:
          $ref: '#/definitions/EnginePool'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/CreatedReference«EngineID,Link»'
          examples: {}
          headers: {}
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequestError'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engine_pools/{id}:
    get:
      tags:
      - Scan Engine
      summary: Engine Pool
      description: Retrieves the details for an engine pool.
      operationId: getEnginePool
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the engine pool.
        required: true
        type: integer
        format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/EnginePool'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    put:
      tags:
      - Scan Engine
      summary: Engine Pool
      description: Updates the specified engine pool.
      operationId: updateScanEnginePool
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the engine pool.
        required: true
        type: integer
        format: int32
      - in: body
        name: enginePool
        description: The details for the scan engine to update.
        required: false
        schema:
          $ref: '#/definitions/EnginePool'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Links'
          examples: {}
          headers: {}
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequestError'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    delete:
      tags:
      - Scan Engine
      summary: Engine Pool
      description: Deletes the specified engine pool.
      operationId: removeScanEnginePool
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the engine pool.
        required: true
        type: integer
        format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Links'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engine_pools/{id}/engines:
    get:
      tags:
      - Scan Engine
      summary: Engine Pool Engines
      description: Get the engines in the engine pool.
      operationId: getScanEnginePoolScanEngines
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the engine pool.
        required: true
        type: integer
        format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ReferencesWith«EngineID,Link»'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    put:
      tags:
      - Scan Engine
      summary: Engine Pool Engines
      description: Set the engines in the engine pool.
      operationId: setScanEnginePoolScanEngines
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the engine pool.
        required: true
        type: integer
        format: int32
      - in: body
        name: engines
        description: The identifiers of the scan engines to place into the engine pool.
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Links'
          examples: {}
          headers: {}
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequestError'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engine_pools/{id}/engines/{engineId}:
    put:
      tags:
      - Scan Engine
      summary: Engine Pool Engines
      description: Add an engine to the engine pool.
      operationId: addScanEnginePoolScanEngine
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the engine pool.
        required: true
        type: integer
        format: int32
      - name: engineId
        in: path
        description: The identifier of the scan engine.
        required: true
        type: integer
        format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Links'
          examples: {}
          headers: {}
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequestError'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    delete:
      tags:
      - Scan Engine
      summary: Engine Pool Engines
      description: Remove the specified engine from the engine pool.
      operationId: removeScanEnginePoolScanEngine
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the engine pool.
        required: true
        type: integer
        format: int32
      - name: engineId
        in: path
        description: The identifier of the scan engine.
        required: true
        type: integer
        format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Links'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engine_pools/{id}/sites:
    get:
      tags:
      - Scan Engine
      summary: Engine Pool Sites
      description: Returns links to the sites associated with this engine pool.
      operationId: getScanEnginePoolSites
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the engine pool.
        required: true
        type: integer
        format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ReferencesWith«SiteID,Link»'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engines:
    get:
      tags:
      - Scan Engine
      summary: Scan Engines
      description: Returns scan engines available to use for scanning.
      operationId: getScanEngines
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters: []
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Resources«ScanEngine»'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    post:
      tags:
      - Scan Engine
      summary: Scan Engines
      description: Creates a new scan engine.
      operationId: createScanEngine
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - in: body
        name: scanEngine
        description: The specification of a scan engine.
        required: false
        schema:
          $ref: '#/definitions/ScanEngine'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ReferenceWith«EngineID,Link»'
          examples: {}
          headers: {}
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequestError'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engines/shared_secret:
    get:
      tags:
      - Scan Engine
      summary: Scan Engine Shared Secret
      description: Returns the current valid shared secret, if one has been previously generated and it has not yet expired; otherwise the endpoint will respond with a 404 status code. Use this endpoint to detect whether a previously-generated shared secret is still valid.
      operationId: getCurrentSharedSecret
      schemes: []
      consumes:
      - application/json
      produces:
      - text/plain
      parameters: []
      responses:
        '200':
          description: OK
          schema:
            type: string
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    post:
      tags:
      - Scan Engine
      summary: Scan Engine Shared Secret
      description: 'Returns the current valid shared secret or generates a new shared secret. The endpoint returns an existing shared secret if one was previously generated and it has not yet expired. Conversely, the endpoint will generate and return a new shared secret for either of the following conditions: a shared secret was not previously generated or the previously-generated shared secret has expired. The shared secret is valid for 60 minutes from the moment it is generated.'
      operationId: createSharedSecret
      schemes: []
      consumes:
      - application/json
      produces:
      - text/plain
      parameters: []
      responses:
        '201':
          description: Created
          schema:
            type: string
          examples: {}
          headers: {}
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequestError'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    delete:
      tags:
      - Scan Engine
      summary: Scan Engine Shared Secret
      description: Revokes the current valid shared secret, if one exists.
      operationId: deleteSharedSecret
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters: []
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Links'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engines/shared_secret/time_to_live:
    get:
      tags:
      - Scan Engine
      summary: Scan Engine Shared Secret Time to live
      description: Returns the number of seconds remaining for the current shared secret before it expires, if one has been previously generated and it has not yet expired; otherwise the endpoint will respond with a 404 status code.
      operationId: getCurrentSharedSecretTimeToLive
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters: []
      responses:
        '200':
          description: OK
          schema:
            type: integer
            format: int64
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engines/{id}:
    get:
      tags:
      - Scan Engine
      summary: Scan Engine
      description: Retrieves the details for a scan engine.
      operationId: getScanEngine
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the scan engine.
        required: true
        type: integer
        format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ScanEngine'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    put:
      tags:
      - Scan Engine
      summary: Scan Engine
      description: Updates the specified scan engine.
      operationId: updateScanEngine
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the scan engine.
        required: true
        type: integer
        format: int32
      - in: body
        name: scanEngine
        description: The specification of the scan engine to update.
        required: false
        schema:
          $ref: '#/definitions/ScanEngine'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Links'
          examples: {}
          headers: {}
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequestError'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
    delete:
      tags:
      - Scan Engine
      summary: Scan Engine
      description: Deletes the specified scan engine.
      operationId: deleteScanEngine
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the scan engine.
        required: true
        type: integer
        format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Links'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engines/{id}/scan_engine_pools:
    get:
      tags:
      - Scan Engine
      summary: Assigned Engine Pools
      description: Retrieves the list of engine pools the scan engine is currently assigned to.
      operationId: getAssignedEnginePools
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the scan engine.
        required: true
        type: integer
        format: int32
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Resources«EnginePool»'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engines/{id}/scans:
    get:
      tags:
      - Scan Engine
      summary: Scan Engine Scans
      description: Returns the scans that have been run on a scan engine.
      operationId: getScanEngineScans
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the scan engine.
        required: true
        type: integer
        format: int32
      - name: page
        in: query
        description: The index of the page (zero-based) to retrieve.
        required: false
        type: integer
        default: 0
        format: int32
      - name: size
        in: query
        description: The number of records per page to retrieve.
        required: false
        type: integer
        default: 10
        format: int32
      - name: sort
        in: query
        description: 'The criteria to sort the records by, in the format: `property[,ASC|DESC]`. The default sort order is ascending. Multiple sort criteria can be specified using multiple sort query parameters.'
        required: false
        type: array
        items:
          type: string
        collectionFormat: multi
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PageOf«Scan»'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
  /api/3/scan_engines/{id}/sites:
    get:
      tags:
      - Scan Engine
      summary: Scan Engine Sites
      description: Retrieves the list of sites the specified scan engine is assigned to.
      operationId: getScanEngineSites
      schemes: []
      consumes:
      - application/json
      produces:
      - application/json;charset=UTF-8
      parameters:
      - name: id
        in: path
        description: The identifier of the scan engine.
        required: true
        type: integer
        format: int32
      - name: page
        in: query
        description: The index of the page (zero-based) to retrieve.
        required: false
        type: integer
        default: 0
        format: int32
      - name: size
        in: query
        description: The number of records per page to retrieve.
        required: false
        type: integer
        default: 10
        format: int32
      - name: sort
        in: query
        description: 'The criteria to sort the records by, in the format: `property[,ASC|DESC]`. The default sort order is ascending. Multiple sort criteria can be specified using multiple sort query parameters.'
        required: false
        type: array
        items:
          type: string
        collectionFormat: multi
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PageOf«Site»'
          examples: {}
          headers: {}
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedError'
          examples: {}
          headers: {}
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/NotFoundError'
          examples: {}
          headers: {}
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
          examples: {}
          headers: {}
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ServiceUnavailableError'
          examples: {}
          headers: {}
      security: []
definitions:
  ScanEngine:
    type: object
    required:
    - address
    - id
    - name
    - port
    properties:
      address:
        type: string
        example: corporate-scan-engine-001.acme.com
        description: The address the scan engine is hosted.
      contentVersion:
        type: string
        example: ''
        description: The content version of the scan engine.
        readOnly: true
      enginePools:
        type: array
        description: A list of identifiers of engine pools this engine is included in.
        readOnly: true
        items:
          type: integer
          format: int32
      id:
        type: integer
        format: int32
        example: 6
        description: The identifier of the scan engine.
      lastRefreshedDate:
        type: string
        example: ''
        description: The date the engine was last refreshed. Date format is in ISO 8601.
        readOnly: true
      lastUpdatedDate:
        type: string
        example: ''
        description: The date the engine was last updated. Date format is in ISO 8601.
        readOnly: true
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        readOnly: true
        items:
          $ref: '#/definitions/Link'
      name:
        type: string
        example: Corporate Scan Engine 001
        description: The name of the scan engine.
      port:
        type: integer
        format: int32
        example: 40894
        description: The port used by the scan engine to communicate with the Security Console.
      productVersion:
        type: string
        example: ''
        description: The product version of the scan engine.
        readOnly: true
      sites:
        type: array
        description: A list of identifiers of each site the scan engine is assigned to.
        items:
          type: integer
          format: int32
      status:
        type: string
        example: ''
        description: "The scan engine status. Can be one of the following values: \n| Value                     | Description                                                                                | \n| ------------------------- | ------------------------------------------------------------------------------------------ | \n| `\"active\"`                | The scan engine is active.                                                                 | \n| `\"incompatible-version\"`  | The product version of the remote scan engine is not compatible with the Security Console. | \n| `\"not-responding\"`        | The scan engine is not responding to the Security Console.                                 | \n| `\"pending-authorization\"` | The Security Console is not yet authorized to connect to the scan engine.                  | \n| `\"unknown\"`               | The status of the scan engine is unknown.                                                  | \n"
        readOnly: true
        enum:
        - active
        - incompatible-version
        - not-responding
        - pending-authorization
        - unknown
    description: ''
  PageOf«Scan»:
    type: object
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      page:
        example: ''
        description: The details of pagination indicating which page was returned, and how the remaining pages can be retrieved.
        $ref: '#/definitions/PageInfo'
      resources:
        type: array
        description: The page of resources returned.
        items:
          $ref: '#/definitions/Scan'
    description: ''
  Scan:
    type: object
    properties:
      assets:
        type: integer
        format: int32
        example: ''
        description: The number of assets found in the scan.
      duration:
        type: string
        example: ''
        description: The duration of the scan in ISO8601 format.
      endTime:
        type: string
        example: ''
        description: The end time of the scan in ISO8601 format.
      engineId:
        type: integer
        format: int32
        example: ''
        description: The identifier of the scan engine.
      engineName:
        type: string
        example: ''
        description: The name of the scan engine.
      id:
        type: integer
        format: int64
        example: ''
        description: The identifier of the scan.
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        readOnly: true
        items:
          $ref: '#/definitions/Link'
      message:
        type: string
        example: ''
        description: The reason for the scan status.
      scanName:
        type: string
        example: ''
        description: The user-driven scan name for the scan.
      scanType:
        type: string
        example: ''
        description: 'The scan type (automated, manual, scheduled). '
      startTime:
        type: string
        example: ''
        description: The start time of the scan in ISO8601 format.
      startedBy:
        type: string
        example: ''
        description: The name of the user that started the scan.
      status:
        type: string
        example: ''
        description: The scan status.
        enum:
        - aborted
        - unknown
        - running
        - finished
        - stopped
        - error
        - paused
        - dispatched
        - integrating
      vulnerabilities:
        example: ''
        description: The vulnerability synopsis of the scan.
        $ref: '#/definitions/Vulnerabilities'
    description: ''
  NotFoundError:
    type: object
    required:
    - status
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      message:
        type: string
        example: An error has occurred.
        description: The messages indicating the cause or reason for failure.
      status:
        type: string
        example: '404'
        description: The HTTP status code for the error (same as in the HTTP response).
        enum:
        - '404'
    description: ''
  InternalServerError:
    type: object
    required:
    - status
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      message:
        type: string
        example: An error has occurred.
        description: The messages indicating the cause or reason for failure.
      status:
        type: string
        example: '500'
        description: The HTTP status code for the error (same as in the HTTP response).
        enum:
        - '500'
    description: ''
  EnginePool:
    type: object
    required:
    - id
    - name
    properties:
      engines:
        type: array
        description: The identifiers of the scan engines in the engine pool.
        items:
          type: integer
          format: int32
      id:
        type: integer
        format: int32
        example: 6
        description: The identifier of the scan engine.
      links:
        type: array
        items:
          $ref: '#/definitions/Link'
      name:
        type: string
        example: Corporate Scan Engine 001
        description: The name of the scan engine.
    description: ''
  Site:
    type: object
    properties:
      assets:
        type: integer
        format: int32
        example: 768
        description: The number of assets that belong to the site.
        readOnly: true
      connectionType:
        type: string
        example: ''
        description: The type of discovery connection configured for the site. This property only applies to dynamic sites.
        readOnly: true
        enum:
        - activesync-ldap
        - activesync-office365
        - activesync-powershell
        - aws
        - dhcp
        - sonar
        - vsphere
      description:
        type: string
        example: ''
        description: The site description.
      id:
        type: integer
        format: int32
        example: ''
        description: The identifier of the site.
      importance:
        type: string
        example: ''
        description: The site importance.
      lastScanTime:
        type: string
        example: ''
        description: The date and time of the site's last scan.
        readOnly: true
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        readOnly: true
        items:
          $ref: '#/definitions/Link'
      name:
        type: string
        example: ''
        description: The site name.
      riskScore:
        type: number
        format: double
        example: 4457823.78
        description: The risk score (with criticality adjustments) of the site.
        readOnly: true
      scanEngine:
        type: integer
        format: int32
        example: ''
        description: The identifier of the scan engine configured in the site.
      scanTemplate:
        type: string
        example: ''
        description: The identifier of the scan template configured in the site.
      type:
        type: string
        example: ''
        description: The type of the site.
        readOnly: true
        enum:
        - agent
        - dynamic
        - static
      vulnerabilities:
        example: ''
        description: Summary information for distinct vulnerabilities found on the assets.
        readOnly: true
        $ref: '#/definitions/Vulnerabilities'
    description: ''
  Links:
    type: object
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
    description: ''
  UnauthorizedError:
    type: object
    required:
    - status
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      message:
        type: string
        example: An error has occurred.
        description: The messages indicating the cause or reason for failure.
      status:
        type: string
        example: '401'
        description: The HTTP status code for the error (same as in the HTTP response).
        enum:
        - '401'
    description: ''
  CreatedReference«EngineID,Link»:
    type: object
    properties:
      id:
        type: integer
        format: int32
        example: 1
        description: The identifier of the resource created.
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
    description: ''
  Vulnerabilities:
    type: object
    properties:
      critical:
        type: integer
        format: int64
        example: 16
        description: The number of critical vulnerabilities.
        readOnly: true
      moderate:
        type: integer
        format: int64
        example: 3
        description: The number of moderate vulnerabilities.
        readOnly: true
      severe:
        type: integer
        format: int64
        example: 76
        description: The number of severe vulnerabilities.
        readOnly: true
      total:
        type: integer
        format: int64
        example: 95
        description: The total number of vulnerabilities.
        readOnly: true
    description: ''
  ServiceUnavailableError:
    type: object
    required:
    - status
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      message:
        type: string
        example: An error has occurred.
        description: The messages indicating the cause or reason for failure.
      status:
        type: string
        example: '503'
        description: The HTTP status code for the error (same as in the HTTP response).
        enum:
        - '503'
    description: ''
  Resources«ScanEngine»:
    type: object
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      resources:
        type: array
        description: The resources returned.
        items:
          $ref: '#/definitions/ScanEngine'
    description: ''
  ReferenceWith«EngineID,Link»:
    type: object
    properties:
      id:
        type: integer
        format: int32
        example: <id>
        description: The identifier of the resource.
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
    description: ''
  Resources«EnginePool»:
    type: object
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      resources:
        type: array
        description: The resources returned.
        items:
          $ref: '#/definitions/EnginePool'
    description: ''
  BadRequestError:
    type: object
    required:
    - status
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      message:
        type: string
        example: An error has occurred.
        description: The messages indicating the cause or reason for failure.
      status:
        type: string
        example: '400'
        description: The HTTP status code for the error (same as in the HTTP response).
        enum:
        - '400'
    description: ''
  ReferencesWith«SiteID,Link»:
    type: object
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      resources:
        type: array
        description: The identifiers of the associated resources.
        items:
          type: integer
          format: int32
    description: ''
  PageOf«Site»:
    type: object
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      page:
        example: ''
        description: The details of pagination indicating which page was returned, and how the remaining pages can be retrieved.
        $ref: '#/definitions/PageInfo'
      resources:
        type: array
        description: The page of resources returned.
        items:
          $ref: '#/definitions/Site'
    description: ''
  ReferencesWith«EngineID,Link»:
    type: object
    properties:
      links:
        type: array
        description: Hypermedia links to corresponding or related resources.
        items:
          $ref: '#/definitions/Link'
      resources:
        type: array
        description: The identifiers of the associated resources.
        items:
          type: integer
          format: int32
    description: ''
  PageInfo:
    type: object
    properties:
      number:
        type: integer
        format: int64
        example: 6
        description: The index (zero-based) of the current page returned.
      size:
        type: integer
        format: int64
        example: 10
        description: The maximum size of the page returned.
      totalPages:
        type: integer
        format: int64
        example: 13
        description: The total number of pages available.
      totalResources:
        type: integer
        format: int64
        example: 123
        description: The total number of resources available across all pages.
    description: ''
  Link:
    type: object
    properties:
      href:
        type: string
        example: https://hostname:3780/api/3/...
        description: 'A hypertext reference, which is either a URI (see <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>) or URI template (see <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc6570">RFC 6570</a>). '
      rel:
        type: string
        example: self
        description: The link relation type. This value is one from the <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc5988#section-6.2">Link Relation Type Registry</a> or is the type of resource being linked to.
    description: ''