========================
CODE SNIPPETS
========================
TITLE: Rapid7 InsightVM API v3 Overview and Structure
DESCRIPTION: This section provides a structured overview of the Rapid7 InsightVM API v3, detailing its core capabilities, architectural principles, documentation organization, and technical specifications. It serves as a guide for understanding the API's design, available modules, and how to get started with integration.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/README.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
InsightVM API v3 Overview:

About InsightVM API:
  - Asset Management: Discover, track, and manage IT assets
  - Vulnerability Assessment: Scan and identify security vulnerabilities
  - Risk Management: Prioritize and track remediation efforts
  - Reporting: Generate comprehensive security reports
  - Site Management: Organize and configure scan targets
  - Policy Compliance: Assess compliance with security policies

API Architecture:
  - REST Design: Follows RESTful design patterns
  - JSON Format: Uses `application/json` media type
  - HATEOAS: Implements Hypermedia as the Engine of Application State
  - HTTPS Required: All connections must use HTTPS
  - Authentication: HTTP Basic Authentication with optional 2FA

Documentation Structure (20 functional modules):
  - Core Management:
    - Administration (6 endpoints)
    - Root (1 endpoint)
  - Asset & Discovery:
    - Assets (25 endpoints)
    - Asset Groups (22 endpoints)
    - Asset Discovery (10 endpoints)
    - Sites (84 endpoints)
  - Security & Scanning:
    - Scans (5 endpoints)
    - Scan Engines (22 endpoints)
    - Scan Templates (5 endpoints)
  - Vulnerability Management:
    - Vulnerabilities (24 endpoints)
    - Vulnerability Checks (4 endpoints)
    - Vulnerability Results (7 endpoints)
    - Vulnerability Exceptions (7 endpoints)
    - Remediation (1 endpoint)
  - Compliance & Policy:
    - Policies (26 endpoints)
    - Policy Overrides (8 endpoints)
  - Reporting & Access:
    - Reports (13 endpoints)
    - Users (32 endpoints)
    - Credentials (6 endpoints)
    - Tags (21 endpoints)

Documentation Features per Endpoint:
  - Request Information:
    - HTTP Method & Path
    - Parameters (detailed with types and examples)
    - Request Body (JSON schema and examples)
    - Authentication (security requirements and permissions)
  - Response Information:
    - Status Codes (all possible HTTP response codes)
    - Response Schemas (complete data structure definitions)
    - JSON Examples (auto-generated realistic response examples)
    - Error Handling (detailed error response formats)
  - Technical Details:
    - Content Types (supported request/response formats)
    - Operation IDs (unique identifiers for code generation)
    - Schema References (links to reusable data models)

Technical Specifications:
  - API Version: v3
  - Base URL: `https://<host>:<port>/api/3/`
  - OpenAPI Version: 2.0 (Swagger)
  - Total Endpoints: 328
  - Schema Definitions: 315
  - Authentication: HTTP Basic + Optional 2FA Token

Getting Started:
1. Authentication Setup: Configure HTTP Basic Authentication credentials
2. Base URL Configuration: Set your InsightVM console URL
3. API Discovery: Start with the Root endpoint to discover available resources
4. Choose Module: Select the appropriate documentation module for your use case
```

----------------------------------------

TITLE: Example JSON Responses for Site Scan API
DESCRIPTION: Provides example JSON payloads for the various responses of the "Start Site Scan" API endpoint. This includes a successful 200 OK response with a scan ID and links, as well as examples for 400, 401, 500, and 503 error responses.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/scan-endpoints.md#_snippet_10

LANGUAGE: JSON
CODE:
```
{
  "id": 1,
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ]
}
```

LANGUAGE: JSON
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "400"
}
```

LANGUAGE: JSON
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "401"
}
```

LANGUAGE: JSON
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "500"
}
```

LANGUAGE: JSON
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "503"
}
```

----------------------------------------

TITLE: Example JSON Response for GET Asset Policy Rules (HTTP 200 OK)
DESCRIPTION: Illustrates the successful (HTTP 200 OK) JSON response structure for the `GET /api/3/assets/{assetId}/policies/{policyId}/rules` endpoint, showing paginated policy rule resources with their compliance details.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/policy-endpoints.md#_snippet_16

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "page": {
    "number": 6,
    "size": 10,
    "totalPages": 13,
    "totalResources": 123
  },
  "resources": [
    {
      "assets": {
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "total": "",
        "totalFailed": "",
        "totalNotApplicable": "",
        "totalPassed": 42
      },
      "benchmark": {
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "name": "",
        "title": "",
        "version": ""
      },
      "description": "",
      "id": "",
      "isCustom": false,
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ],
      "name": "",
      "role": "",
      "scope": "",
      "status": "",
      "surrogateId": "",
      "title": ""
    }
  ]
}
```

----------------------------------------

TITLE: Rapid7 InsightVM API: Get All Users Endpoint Documentation
DESCRIPTION: Detailed documentation for the `GET /api/3/users` endpoint, used to retrieve a paginated list of all defined users. Includes query parameters for pagination and sorting, and examples of successful and error responses.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/user-endpoints.md#_snippet_20

LANGUAGE: APIDOC
CODE:
```
Endpoint: GET /api/3/users
Description: Returns all defined users. Global Administrator
Operation ID: getUsers
Parameters:
  - Name: page
    Location: query
    Type: integer
    Required: No
    Description: The index of the page (zero-based) to retrieve.
  - Name: size
    Location: query
    Type: integer
    Required: No
    Description: The number of records per page to retrieve.
  - Name: sort
    Location: query
    Type: array
    Required: No
    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.
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "page": {
    "number": 6,
    "size": 10,
    "totalPages": 13,
    "totalResources": 123
  },
  "resources": [
    {
      "authentication": {
        "external": false,
        "id": "",
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "name": "",
        "type": ""
      },
      "email": "",
      "enabled": false,
      "id": "",
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ],
      "locale": {
        "default": "",
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "reports": ""
      },
      "locked": false,
      "login": "",
      "name": "",
      "role": {
        "allAssetGroups": false,
        "allSites": false,
        "id": "",
        "name": "",
        "privileges": [
          "all-permissions"
        ],
        "superuser": false
      }
    }
  ]
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "401"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "404"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "500"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "503"
}
```

----------------------------------------

TITLE: Rapid7 InsightVM API: Example JSON for AssetCreate Request Body
DESCRIPTION: Provides a comprehensive JSON example illustrating the structure and typical values for the `AssetCreate` request body. This example demonstrates how to populate various fields such as addresses, hostnames, OS fingerprints, services, and software when adding or updating an asset via the Rapid7 InsightVM API.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/asset-endpoints.md#_snippet_9

LANGUAGE: JSON
CODE:
```
{
  "addresses": [
    {
      "ip": "123.245.34.235",
      "mac": "12:34:56:78:90:AB"
    }
  ],
  "assessedForPolicies": false,
  "assessedForVulnerabilities": true,
  "configurations": [
    {
      "name": "<name>",
      "value": "<value>"
    }
  ],
  "cpe": "",
  "databases": [
    {
      "description": "Microsoft SQL Server",
      "id": 13,
      "name": "MSSQL"
    }
  ],
  "date": "",
  "description": "",
  "files": [
    {
      "attributes": [
        {
          "name": "<name>",
          "value": "<value>"
        }
      ],
      "name": "ADMIN$",
      "size": -1,
      "type": "directory"
    }
  ],
  "history": [
    {
      "date": "2018-04-09T06:23:49Z",
      "description": "",
      "scanId": 12,
      "type": "SCAN",
      "user": "",
      "version": 8,
      "vulnerabilityExceptionId": ""
    }
  ],
  "hostName": {
    "name": "corporate-workstation-1102DC.acme.com",
    "source": "DNS"
  },
  "hostNames": [
    {
      "name": "corporate-workstation-1102DC.acme.com",
      "source": "DNS"
    }
  ],
  "id": 282,
  "ids": [
    {
      "id": "c56b2c59-4e9b-4b89-85e2-13f8146eb071",
      "source": "WQL"
    }
  ],
  "ip": "182.34.74.202",
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "mac": "AB:12:CD:34:EF:56",
  "os": "",
  "osCertainty": "",
  "osFingerprint": {
    "architecture": "x86",
    "configurations": [
      {
        "name": "<name>",
        "value": "<value>"
      }
    ],
    "cpe": {
      "edition": "enterprise",
      "language": "",
      "other": "",
      "part": "o",
      "product": "windows_server_2008",
      "swEdition": "",
      "targetHW": "",
      "targetSW": "",
      "update": "sp1",
      "v2.2": "cpe:/o:microsoft:windows_server_2008:-:sp1:enterprise",
      "v2.3": "cpe:2.3:o:microsoft:windows_server_2008:-:sp1:enterprise:*:*:*:*:*",
      "vendor": "microsoft",
      "version": "-"
    },
    "description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
    "family": "Windows",
    "id": 35,
    "product": "Windows Server 2008 Enterprise Edition",
    "systemName": "Microsoft Windows",
    "type": "Workstation",
    "vendor": "Microsoft",
    "version": "SP1"
  },
  "rawRiskScore": 31214.3,
  "riskScore": 37457.16,
  "services": [
    {
      "configurations": [
        {
          "name": "<name>",
          "value": "<value>"
        }
      ],
      "databases": [
        {
          "description": "Microsoft SQL Server",
          "id": 13,
          "name": "MSSQL"
        }
      ],
      "family": "",
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ],
      "name": "CIFS Name Service",
      "port": 139,
      "product": "Samba",
      "protocol": "tcp",
      "userGroups": [
        {
          "id": 972,
          "name": "Administrators"
        }
      ],
      "users": [
        {
          "fullName": "Smith, John",
          "id": 8952,
          "name": "john_smith"
        }
      ],
      "vendor": "",
      "version": "3.5.11",
      "webApplications": [
        {
          "id": 30712,
          "pages": [
            {
              "linkType": "html-ref",
              "path": "/docs/config/index.html",
              "response": 200
            }
          ],
          "root": "/",
          "virtualHost": "102.89.22.253"
        }
      ]
    }
  ],
  "software": [
    {
      "configurations": [
        {
          "name": "<name>",
          "value": "<value>"
        }
      ],
      "cpe": {
        "edition": "enterprise",
        "language": "",
        "other": "",
        "part": "o",
        "product": "windows_server_2008",
        "swEdition": "",
        "targetHW": "",
        "targetSW": "",
        "update": "sp1",
        "v2.2": "cpe:/o:microsoft:windows_server_2008:-:sp1:enterprise",
        "v2.3": "cpe:2.3:o:microsoft:windows_server_2008:-:sp1:enterprise:*:*:*:*:*",
        "vendor": "microsoft",
        "version": "-"
      },
      "description": "Microsoft Outlook 2013 15.0.4867.1000",
      "family": "Office 2013",
      "id": 42,
      "product": "Outlook 2013",
      "type": "Productivity",
      "vendor": "Microsoft",
      "version": "15.0.4867.1000"
    }
  ],
  "type": "",
  "userGroups": [
    {
      "id": 972,
      "name": "Administrators"
    }
  ],
  "users": [
    {
      "fullName": "Smith, John",
      "id": 8952,
      "name": "john_smith"
    }
  ],
  "vulnerabilities": {
    "critical": 16,
    "exploits": 4,
    "malwareKits": 0,
    "moderate": 3,
    "severe": 76,
    "total": 95
  }
}
```

----------------------------------------

TITLE: Example JSON Response for Get Vulnerability Affected Assets (200 OK)
DESCRIPTION: Provides an example of a successful HTTP 200 OK response for the 'Get Vulnerability Affected Assets' endpoint. This response lists the `resources` (asset IDs) affected by the specified vulnerability, conforming to the `ReferencesWith«AssetID,Link»` schema.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/vulnerability-endpoints.md#_snippet_29

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "resources": [
    42
  ]
}
```

----------------------------------------

TITLE: Retrieve Software Installed on an Asset (GET /api/3/assets/{id}/software)
DESCRIPTION: This API endpoint allows users to retrieve a list of software installed on a specific asset within Rapid7 InsightVM. It requires an asset identifier and returns a collection of software resources, including details like product name, vendor, version, and CPE information. Various HTTP status codes are covered, including success and common errors.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/asset-endpoints.md#_snippet_47

LANGUAGE: APIDOC
CODE:
```
Endpoint: GET /api/3/assets/{id}/software
Description: Returns the software on an asset.
Operation ID: getAssetSoftware

Parameters:
  - Name: id
    Location: path
    Type: integer
    Required: Yes
    Description: The identifier of the asset.

Responses:
  - Status: 200
    Description: OK
    Schema: Resources«Software»
  - Status: 401
    Description: Unauthorized
    Schema: UnauthorizedError
  - Status: 404
    Description: Not Found
    Schema: NotFoundError
  - Status: 500
    Description: Internal Server Error
    Schema: InternalServerError
  - Status: 503
    Description: Service Unavailable
    Schema: ServiceUnavailableError

Request Content-Type: application/json
Response Content-Type: application/json;charset=UTF-8
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "resources": [
    {
      "configurations": [
        {
          "name": "<name>",
          "value": "<value>"
        }
      ],
      "cpe": {
        "edition": "enterprise",
        "language": "",
        "other": "",
        "part": "o",
        "product": "windows_server_2008",
        "swEdition": "",
        "targetHW": "",
        "targetSW": "",
        "update": "sp1",
        "v2.2": "cpe:/o:microsoft:windows_server_2008:-:sp1:enterprise",
        "v2.3": "cpe:2.3:o:microsoft:windows_server_2008:-:sp1:enterprise:*:*:*:*:*",
        "vendor": "microsoft",
        "version": "-"
      },
      "description": "Microsoft Outlook 2013 15.0.4867.1000",
      "family": "Office 2013",
      "id": 42,
      "product": "Outlook 2013",
      "type": "Productivity",
      "vendor": "Microsoft",
      "version": "15.0.4867.1000"
    }
  ]
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "401"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "404"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "500"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "503"
}
```

----------------------------------------

TITLE: Rapid7 InsightVM API: Example JSON for AssetCreate Body
DESCRIPTION: Provides a comprehensive JSON example payload for the `asset` body parameter, illustrating the expected data structure when creating or updating an asset in the Rapid7 InsightVM API. This example includes various nested objects and arrays for addresses, configurations, OS fingerprints, services, and software.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/asset-endpoints.md#_snippet_7

LANGUAGE: JSON
CODE:
```
{
  "addresses": [
    {
      "ip": "123.245.34.235",
      "mac": "12:34:56:78:90:AB"
    }
  ],
  "assessedForPolicies": false,
  "assessedForVulnerabilities": true,
  "configurations": [
    {
      "name": "<name>",
      "value": "<value>"
    }
  ],
  "cpe": "",
  "databases": [
    {
      "description": "Microsoft SQL Server",
      "id": 13,
      "name": "MSSQL"
    }
  ],
  "date": "",
  "description": "",
  "files": [
    {
      "attributes": [
        {
          "name": "<name>",
          "value": "<value>"
        }
      ],
      "name": "ADMIN$",
      "size": -1,
      "type": "directory"
    }
  ],
  "history": [
    {
      "date": "2018-04-09T06:23:49Z",
      "description": "",
      "scanId": 12,
      "type": "SCAN",
      "user": "",
      "version": 8,
      "vulnerabilityExceptionId": ""
    }
  ],
  "hostName": {
    "name": "corporate-workstation-1102DC.acme.com",
    "source": "DNS"
  },
  "hostNames": [
    {
      "name": "corporate-workstation-1102DC.acme.com",
      "source": "DNS"
    }
  ],
  "id": 282,
  "ids": [
    {
      "id": "c56b2c59-4e9b-4b89-85e2-13f8146eb071",
      "source": "WQL"
    }
  ],
  "ip": "182.34.74.202",
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "mac": "AB:12:CD:34:EF:56",
  "os": "",
  "osCertainty": "",
  "osFingerprint": {
    "architecture": "x86",
    "configurations": [
      {
        "name": "<name>",
        "value": "<value>"
      }
    ],
    "cpe": {
      "edition": "enterprise",
      "language": "",
      "other": "",
      "part": "o",
      "product": "windows_server_2008",
      "swEdition": "",
      "targetHW": "",
      "targetSW": "",
      "update": "sp1",
      "v2.2": "cpe:/o:microsoft:windows_server_2008:-:sp1:enterprise",
      "v2.3": "cpe:2.3:o:microsoft:windows_server_2008:-:sp1:enterprise:*:*:*:*:*",
      "vendor": "microsoft",
      "version": "-"
    },
    "description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
    "family": "Windows",
    "id": 35,
    "product": "Windows Server 2008 Enterprise Edition",
    "systemName": "Microsoft Windows",
    "type": "Workstation",
    "vendor": "Microsoft",
    "version": "SP1"
  },
  "rawRiskScore": 31214.3,
  "riskScore": 37457.16,
  "services": [
    {
      "configurations": [
        {
          "name": "<name>",
          "value": "<value>"
        }
      ],
      "databases": [
        {
          "description": "Microsoft SQL Server",
          "id": 13,
          "name": "MSSQL"
        }
      ],
      "family": "",
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ],
      "name": "CIFS Name Service",
      "port": 139,
      "product": "Samba",
      "protocol": "tcp",
      "userGroups": [
        {
          "id": 972,
          "name": "Administrators"
        }
      ],
      "users": [
        {
          "fullName": "Smith, John",
          "id": 8952,
          "name": "john_smith"
        }
      ],
      "vendor": "",
      "version": "3.5.11",
      "webApplications": [
        {
          "id": 30712,
          "pages": [
            {
              "linkType": "html-ref",
              "path": "/docs/config/index.html",
              "response": 200
            }
          ],
          "root": "/",
          "virtualHost": "102.89.22.253"
        }
      ]
    }
  ],
  "software": [
    {
      "configurations": [
        {
          "name": "<name>",
          "value": "<value>"
        }
      ],
      "cpe": {
        "edition": "enterprise",
        "language": "",
        "other": "",
        "part": "o",
        "product": "windows_server_2008",
        "swEdition": "",
        "targetHW": "",
        "targetSW": "",
        "update": "sp1",
        "v2.2": "cpe:/o:microsoft:windows_server_2008:-:sp1:enterprise",
        "v2.3": "cpe:2.3:o:microsoft:windows_server_2008:-:sp1:enterprise:*:*:*:*:*",
        "vendor": "microsoft",
        "version": "-"
      },
      "description": "Microsoft Outlook 2013 15.0.4867.1000",
      "family": "Office 2013",
      "id": 42,
      "product": "Outlook 2013",
      "type": "Productivity",
      "vendor": "Microsoft",
      "version": "15.0.4867.1000"
    }
  ],
  "type": "",
  "userGroups": [
    {
      "id": 972,
      "name": "Administrators"
    }
  ],
  "users": [
    {
      "fullName": "Smith, John",
      "id": 8952,
      "name": "john_smith"
    }
  ],
  "vulnerabilities": {
    "critical": 16,
    "exploits": 4,
    "malwareKits": 0,
    "moderate": 3,
    "severe": 76,
    "total": 95
  }
}
```

----------------------------------------

TITLE: Rapid7 InsightVM API: Agent Resource 200 OK Response Example
DESCRIPTION: This snippet documents the successful (HTTP 200 OK) response for an API request to retrieve agent details from the Rapid7 InsightVM API. It includes the schema name and a comprehensive JSON example illustrating the structure of a paginated list of agent objects, detailing their various attributes like network configurations, historical data, operating system fingerprints, services, and installed software.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/asset-group-endpoints.md#_snippet_1

LANGUAGE: APIDOC
CODE:
```
HTTP Status: 200 OK
Description: Successful retrieval of agent resources.
Schema: PageOf«Agent»
```

LANGUAGE: JSON
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "page": {
    "number": 6,
    "size": 10,
    "totalPages": 13,
    "totalResources": 123
  },
  "resources": [
    {
      "addresses": [
        {
          "ip": "123.245.34.235",
          "mac": "12:34:56:78:90:AB"
        }
      ],
      "agentId": "fe1708451f8c78c3a20a8a79818878e1",
      "assessedForPolicies": false,
      "assessedForVulnerabilities": true,
      "configurations": [
        {
          "name": "<name>",
          "value": "<value>"
        }
      ],
      "databases": [
        {
          "description": "Microsoft SQL Server",
          "id": 13,
          "name": "MSSQL"
        }
      ],
      "files": [
        {
          "attributes": [
            {
              "name": "<name>",
              "value": "<value>"
            }
          ],
          "name": "ADMIN$",
          "size": -1,
          "type": "directory"
        }
      ],
      "history": [
        {
          "date": "2018-04-09T06:23:49Z",
          "description": "",
          "scanId": 12,
          "type": "SCAN",
          "user": "",
          "version": 8,
          "vulnerabilityExceptionId": ""
        }
      ],
      "hostName": "corporate-workstation-1102DC.acme.com",
      "hostNames": [
        {
          "name": "corporate-workstation-1102DC.acme.com",
          "source": "DNS"
        }
      ],
      "id": 282,
      "ids": [
        {
          "id": "c56b2c59-4e9b-4b89-85e2-13f8146eb071",
          "source": "WQL"
        }
      ],
      "ip": "182.34.74.202",
      "lastAssessedForVulnerabilities": "2019-09-11T10:39:51.288Z",
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ],
      "mac": "AB:12:CD:34:EF:56",
      "os": "Microsoft Windows Server 2008 Enterprise Edition SP1",
      "osCertainty": "0.75",
      "osFingerprint": {
        "architecture": "x86",
        "configurations": [
          {
            "name": "<name>",
            "value": "<value>"
          }
        ],
        "cpe": {
          "edition": "enterprise",
          "language": "",
          "other": "",
          "part": "o",
          "product": "windows_server_2008",
          "swEdition": "",
          "targetHW": "",
          "targetSW": "",
          "update": "sp1"
        },
        "description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
        "family": "Windows",
        "id": 35,
        "product": "Windows Server 2008 Enterprise Edition",
        "systemName": "Microsoft Windows",
        "type": "Workstation",
        "vendor": "Microsoft",
        "version": "SP1"
      },
      "rawRiskScore": 31214.3,
      "riskScore": 37457.16,
      "services": [
        {
          "configurations": [
            {
              "name": "<name>",
              "value": "<value>"
            }
          ],
          "databases": [
            {
              "description": "Microsoft SQL Server",
              "id": 13,
              "name": "MSSQL"
            }
          ],
          "family": "",
          "links": [
            {
              "href": "https://hostname:3780/api/3/...",
              "rel": "self"
            }
          ],
          "name": "CIFS Name Service",
          "port": 139,
          "product": "Samba",
          "protocol": "tcp",
          "userGroups": [
            {
              "id": 972,
              "name": "Administrators"
            }
          ],
          "users": [
            {
              "fullName": "Smith, John",
              "id": 8952,
              "name": "john_smith"
            }
          ],
          "vendor": "",
          "version": "3.5.11",
          "webApplications": [
            {
              "id": 30712,
              "pages": [
                {
                  "linkType": "html-ref",
                  "path": "/docs/config/index.html",
                  "response": 200
                }
              ],
              "root": "/",
              "virtualHost": "102.89.22.253"
            }
          ]
        }
      ],
      "software": [
        {
          "configurations": [
            {
              "name": "<name>",
              "value": "<value>"
            }
          ],
          "cpe": {
            "edition": "enterprise",
            "language": "",
            "other": "",
            "part": "o",
            "product": "windows_server_2008",
            "swEdition": "",
            "targetHW": "",
            "targetSW": "",
            "update": "sp1"
          }
        }
      ]
    }
  ]
}
```

----------------------------------------

TITLE: Rapid7 InsightVM API: Example JSON for ScanTemplate Request Body
DESCRIPTION: Provides a comprehensive JSON example illustrating the structure and typical values for the `scanTemplate` request body. This example demonstrates how to configure various scan parameters, including check categories, discovery settings, and web scanning options.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/scan-template-endpoints.md#_snippet_23

LANGUAGE: json
CODE:
```
{
  "checks": {
    "categories": {
      "disabled": [
        "string"
      ],
      "enabled": [
        "string"
      ],
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ]
    },
    "correlate": false,
    "individual": {
      "disabled": [
        "string"
      ],
      "enabled": [
        "string"
      ],
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ]
    },
    "links": [
      {
        "href": "https://hostname:3780/api/3/...",
        "rel": "self"
      }
    ],
    "potential": false,
    "types": {
      "disabled": [
        "string"
      ],
      "enabled": [
        "string"
      ],
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ]
    },
    "unsafe": false
  },
  "database": {
    "db2": "database",
    "links": [
      {
        "href": "https://hostname:3780/api/3/...",
        "rel": "self"
      }
    ],
    "oracle": [
      "string"
    ],
    "postgres": "postgres"
  },
  "description": "Performs a full network audit of all systems using only safe checks...",
  "discovery": {
    "asset": {
      "collectWhoisInformation": false,
      "fingerprintMinimumCertainty": 0.16,
      "fingerprintRetries": 0,
      "ipFingerprintingEnabled": true,
      "sendArpPings": true,
      "sendIcmpPings": true,
      "tcpPorts": [
        42
      ],
      "treatTcpResetAsAsset": true,
      "udpPorts": [
        42
      ]
    },
    "performance": {
      "packetRate": {
        "defeatRateLimit": true,
        "maximum": 15000,
        "minimum": 450
      },
      "parallelism": {
        "maximum": 0,
        "minimum": 0
      },
      "retryLimit": 3,
      "scanDelay": {
        "maximum": "PT0S",
        "minimum": "PT0S"
      },
      "timeout": {
        "initial": "PT0.5S",
        "maximum": "PT3S",
        "minimum": "PT0S"
      }
    },
    "service": {
      "serviceNameFile": "",
      "tcp": {
        "additionalPorts": [
          {}
        ],
        "excludedPorts": [
          {}
        ],
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "method": "SYN",
        "ports": "well-known"
      },
      "udp": {
        "additionalPorts": [
          {}
        ],
        "excludedPorts": [
          {}
        ],
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "ports": "well-known"
      }
    }
  },
  "discoveryOnly": false,
  "enableWindowsServices": false,
  "enhancedLogging": false,
  "id": "full-audit-without-web-spider",
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "maxParallelAssets": 10,
  "maxScanProcesses": 10,
  "name": "Full audit",
  "policy": {
    "enabled": [
      42
    ],
    "links": [
      {
        "href": "https://hostname:3780/api/3/...",
        "rel": "self"
      }
    ],
    "recursiveWindowsFSSearch": false,
    "storeSCAP": false
  },
  "policyEnabled": true,
  "telnet": {
    "characterSet": "ASCII",
    "failedLoginRegex": "(?:[i,I]ncorrect|[u,U]nknown|[f,F]ail|[i,I]nvalid|[l,L]ogin|[p,P]assword|[p,P]asswd|[u,U]sername|[u,U]nable|[e,E]rror|[d,D]enied|[r,R]eject|[r,R]efuse|[c,C]lose|[c,C]losing|Not on system console|% Bad)",
    "links": [
      {
        "href": "https://hostname:3780/api/3/...",
        "rel": "self"
      }
    ],
    "loginRegex": "(?:[l,L]ogin|[u,U]ser.?[nN]ame) *\\:",
    "passwordPromptRegex": "(?:[p,P]assword|[p,P]asswd) *\\:",
    "questionableLoginRegex": "(?:[l,L]ast [l,L]ogin *\\:|allows only .* Telnet Client License)"
  },
  "vulnerabilityEnabled": true,
  "web": {
    "dontScanMultiUseDevices": true,
    "includeQueryStrings": false,
    "paths": {
      "boostrap": "/root",
      "excluded": "/root/sensitive.html",
      "honorRobotDirectives": false
    },
    "patterns": {
      "sensitiveContent": "",
      "sensitiveField": "(p|pass)(word|phrase|wd|code)"
    },
    "performance": {
      "httpDaemonsToSkip": [
        "string"
      ],
      "maximumDirectoryLevels": 6,
      "maximumForeignHosts": 100,
      "maximumLinkDepth": 6,
      "maximumPages": 3000,
      "maximumRetries": 2,
      "maximumTime": "PT0S",
      "responseTimeout": "PT2M",
      "threadsPerServer": 3
    },
    "testCommonUsernamesAndPasswords": false,
    "testXssInSingleScan": false,
    "userAgent": "Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 6.0; .NET CLR 1.1.4322; .NET CLR 2.0.50727)"
  },
  "webEnabled": true
}
```

----------------------------------------

TITLE: Example JSON for ScanTemplate Request Body
DESCRIPTION: A comprehensive JSON example illustrating the structure and typical values for the `ScanTemplate` object. This example demonstrates how to configure various aspects of a scan, including vulnerability checks, database settings, network discovery parameters, and web application scanning options.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/scan-template-endpoints.md#_snippet_10

LANGUAGE: json
CODE:
```
{
  "checks": {
    "categories": {
      "disabled": [
        "string"
      ],
      "enabled": [
        "string"
      ],
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ]
    },
    "correlate": false,
    "individual": {
      "disabled": [
        "string"
      ],
      "enabled": [
        "string"
      ],
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ]
    },
    "links": [
      {
        "href": "https://hostname:3780/api/3/...",
        "rel": "self"
      }
    ],
    "potential": false,
    "types": {
      "disabled": [
        "string"
      ],
      "enabled": [
        "string"
      ],
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ]
    },
    "unsafe": false
  },
  "database": {
    "db2": "database",
    "links": [
      {
        "href": "https://hostname:3780/api/3/...",
        "rel": "self"
      }
    ],
    "oracle": [
      "string"
    ],
    "postgres": "postgres"
  },
  "description": "Performs a full network audit of all systems using only safe checks...",
  "discovery": {
    "asset": {
      "collectWhoisInformation": false,
      "fingerprintMinimumCertainty": 0.16,
      "fingerprintRetries": 0,
      "ipFingerprintingEnabled": true,
      "sendArpPings": true,
      "sendIcmpPings": true,
      "tcpPorts": [
        42
      ],
      "treatTcpResetAsAsset": true,
      "udpPorts": [
        42
      ]
    },
    "performance": {
      "packetRate": {
        "defeatRateLimit": true,
        "maximum": 15000,
        "minimum": 450
      },
      "parallelism": {
        "maximum": 0,
        "minimum": 0
      },
      "retryLimit": 3,
      "scanDelay": {
        "maximum": "PT0S",
        "minimum": "PT0S"
      },
      "timeout": {
        "initial": "PT0.5S",
        "maximum": "PT3S",
        "minimum": "PT0S"
      }
    },
    "service": {
      "serviceNameFile": "",
      "tcp": {
        "additionalPorts": [
          {}
        ],
        "excludedPorts": [
          {}
        ],
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "method": "SYN",
        "ports": "well-known"
      },
      "udp": {
        "additionalPorts": [
          {}
        ],
        "excludedPorts": [
          {}
        ],
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "ports": "well-known"
      }
    }
  },
  "discoveryOnly": false,
  "enableWindowsServices": false,
  "enhancedLogging": false,
  "id": "full-audit-without-web-spider",
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "maxParallelAssets": 10,
  "maxScanProcesses": 10,
  "name": "Full audit",
  "policy": {
    "enabled": [
      42
    ],
    "links": [
      {
        "href": "https://hostname:3780/api/3/...",
        "rel": "self"
      }
    ],
    "recursiveWindowsFSSearch": false,
    "storeSCAP": false
  },
  "policyEnabled": true,
  "telnet": {
    "characterSet": "ASCII",
    "failedLoginRegex": "(?:[i,I]ncorrect|[u,U]nknown|[f,F]ail|[i,I]nvalid|[l,L]ogin|[p,P]assword|[p,P]asswd|[u,U]sername|[u,U]nable|[e,E]rror|[d,D]enied|[r,R]eject|[r,R]efuse|[c,C]lose|[c,C]losing|Not on system console|% Bad)",
    "links": [
      {
        "href": "https://hostname:3780/api/3/...",
        "rel": "self"
      }
    ],
    "loginRegex": "(?:[l,L]ogin|[u,U]ser.?[nN]ame) *\\:",
    "passwordPromptRegex": "(?:[p,P]assword|[p,P]asswd) *\\:",
    "questionableLoginRegex": "(?:[l,L]ast [l,L]ogin *\\:|allows only .* Telnet Client License)"
  },
  "vulnerabilityEnabled": true,
  "web": {
    "dontScanMultiUseDevices": true,
    "includeQueryStrings": false,
    "paths": {
      "boostrap": "/root",
      "excluded": "/root/sensitive.html",
      "honorRobotDirectives": false
    },
    "patterns": {
      "sensitiveContent": "",
      "sensitiveField": "(p|pass)(word|phrase|wd|code)"
    },
    "performance": {
      "httpDaemonsToSkip": [
        "string"
      ],
      "maximumDirectoryLevels": 6,
      "maximumForeignHosts": 100,
      "maximumLinkDepth": 6,
      "maximumPages": 3000,
      "maximumRetries": 2,
      "maximumTime": "PT0S",
      "responseTimeout": "PT2M",
      "threadsPerServer": 3
    },
    "testCommonUsernamesAndPasswords": false,
    "testXssInSingleScan": false,
    "userAgent": "Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 6.0; .NET CLR 1.1.4322; .NET CLR 2.0.50727)"
  },
  "webEnabled": true
}
```

----------------------------------------

TITLE: Retrieve Single Operating System Details (GET /api/3/operating_systems/{id})
DESCRIPTION: API endpoint documentation for retrieving a specific operating system's details by its unique identifier. This includes the endpoint path, required parameters, and a successful (200 OK) response example.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/asset-endpoints.md#_snippet_57

LANGUAGE: APIDOC
CODE:
```
Endpoint: GET /api/3/operating_systems/{id}
Operation ID: getOperatingSystem
Description: Returns the details for an operating system.

Parameters:
  Name: id
  Location: path
  Type: integer
  Required: Yes
  Description: The identifier of the operating system.

Request Content-Type: application/json
Response Content-Type: application/json;charset=UTF-8
```

LANGUAGE: APIDOC
CODE:
```
200: OK
Schema: OperatingSystem
```

LANGUAGE: JSON
CODE:
```
{
  "architecture": "x86",
  "configurations": [
    {
      "name": "<name>",
      "value": "<value>"
    }
  ],
  "cpe": {
    "edition": "enterprise",
    "language": "",
    "other": "",
    "part": "o",
    "product": "windows_server_2008",
    "swEdition": "",
    "targetHW": "",
    "targetSW": "",
    "update": "sp1",
    "v2.2": "cpe:/o:microsoft:windows_server_2008:-:sp1:enterprise",
    "v2.3": "cpe:2.3:o:microsoft:windows_server_2008:-:sp1:enterprise:*:*:*:*:*",
    "vendor": "microsoft",
    "version": "-"
  },
  "description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
  "family": "Windows",
  "id": 35,
  "product": "Windows Server 2008 Enterprise Edition",
  "systemName": "Microsoft Windows",
  "type": "Workstation",
  "vendor": "Microsoft",
  "version": "SP1"
}
```

----------------------------------------

TITLE: API Error Response: 404 Not Found Example
DESCRIPTION: Provides an example JSON response for a 404 Not Found error. This status code indicates that the server cannot find the requested resource.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/user-endpoints.md#_snippet_9

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "404"
}
```

----------------------------------------

TITLE: Rapid7 InsightVM API: Get Administration Properties
DESCRIPTION: Documents the `GET /api/3/administration/properties` endpoint, which retrieves system details including host and version information. It outlines the request/response content types and provides example JSON responses for successful (200 OK) and various error scenarios (401 Unauthorized, 404 Not Found, 500 Internal Server Error, 503 Service Unavailable).

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/administration-endpoints.md#_snippet_8

LANGUAGE: APIDOC
CODE:
```
Endpoint: GET /api/3/administration/properties
Description: Returns system details, including host and version information.
Operation ID: getProperties
Request Content-Type: multipart/form-data
Response Content-Type: application/json;charset=UTF-8

Responses:
  200 OK (Schema: EnvironmentProperties)
  401 Unauthorized (Schema: UnauthorizedError)
  404 Not Found (Schema: NotFoundError)
  500 Internal Server Error (Schema: InternalServerError)
  503 Service Unavailable (Schema: ServiceUnavailableError)
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "properties": {}
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "401"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "404"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "500"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "503"
}
```

----------------------------------------

TITLE: API Response Example for HTTP 200 OK
DESCRIPTION: Illustrates a successful HTTP 200 OK response for the Rapid7 InsightVM API, detailing the `PolicySummaryResource` schema and providing an example JSON payload for policy compliance information.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/policy-endpoints.md#_snippet_72

LANGUAGE: APIDOC
CODE:
```
Schema: PolicySummaryResource
```

LANGUAGE: json
CODE:
```
{
  "decreasedCompliance": "",
  "increasedCompliance": "",
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "numberOfPolicies": "",
  "overallCompliance": "",
  "scannedPolicies": ""
}
```

----------------------------------------

TITLE: API Endpoint: Get Asset Services
DESCRIPTION: Documents the `GET /api/3/assets/{id}/services` endpoint, which retrieves all services discovered on a specific asset. It details the required path parameter and possible HTTP responses with their schemas and example JSON payloads.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/asset-endpoints.md#_snippet_36

LANGUAGE: APIDOC
CODE:
```
Endpoint: GET /api/3/assets/{id}/services
Description: Returns the services discovered on an asset.
Operation ID: getAssetServices

Parameters:
  - Name: id
    Location: path
    Type: integer
    Required: Yes
    Description: The identifier of the asset.

Responses:
  - Status: 200 OK
    Description: OK
    Schema: ReferencesWith«ReferenceWithEndpointIDLink,ServiceLink»
    Example JSON Response:
      {
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "port": 22,
            "protocol": "tcp",
            "rel": "Service"
          }
        ],
        "resources": [
          {
            "links": [
              {
                "href": "https://hostname:3780/api/3/...",
                "rel": "self"
              }
            ],
            "port": 22,
            "protocol": "tcp"
          }
        ]
      }
  - Status: 401 Unauthorized
    Description: Unauthorized
    Schema: UnauthorizedError
    Example JSON Response:
      {
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "message": "An error has occurred.",
        "status": "401"
      }
  - Status: 404 Not Found
    Description: Not Found
    Schema: NotFoundError
    Example JSON Response:
      {
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "message": "An error has occurred.",
        "status": "404"
      }
  - Status: 500 Internal Server Error
    Description: Internal Server Error
    Schema: InternalServerError
    Example JSON Response:
      {
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "message": "An error has occurred.",
        "status": "500"
      }
  - Status: 503 Service Unavailable
    Description: Service Unavailable
    Schema: ServiceUnavailableError
    Example JSON Response:
      {
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "message": "An error has occurred.",
        "status": "503"
      }
```

----------------------------------------

TITLE: Common API Response: 404 Not Found Example
DESCRIPTION: Example JSON response for a not found (404) API call. This response indicates that the server cannot find the requested resource.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/policy-endpoints.md#_snippet_29

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "404"
}
```

----------------------------------------

TITLE: Example JSON Response for HTTP 200 OK (General)
DESCRIPTION: Illustrates the generic structure of a successful (HTTP 200 OK) API response, typically returning a paginated list of resources like PolicyRule objects.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/policy-endpoints.md#_snippet_10

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "page": {
    "number": 6,
    "size": 10,
    "totalPages": 13,
    "totalResources": 123
  },
  "resources": [
    {
      "assets": {
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "total": "",
        "totalFailed": "",
        "totalNotApplicable": "",
        "totalPassed": 42
      },
      "benchmark": {
        "links": [
          {
            "href": "https://hostname:3780/api/3/...",
            "rel": "self"
          }
        ],
        "name": "",
        "title": "",
        "version": ""
      },
      "description": "",
      "id": "",
      "isCustom": false,
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ],
      "name": "",
      "role": "",
      "scope": "",
      "status": "",
      "surrogateId": "",
      "title": ""
    }
  ]
}
```

----------------------------------------

TITLE: Example JSON Response for GET Asset Policy Rules (HTTP 401 Unauthorized)
DESCRIPTION: Shows the JSON structure for an HTTP 401 Unauthorized error response specific to the `GET /api/3/assets/{assetId}/policies/{policyId}/rules` endpoint, indicating authentication failure.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/policy-endpoints.md#_snippet_17

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "401"
}
```

----------------------------------------

TITLE: Rapid7 InsightVM API: 404 Not Found Response Example
DESCRIPTION: An example JSON response for a not found (404 Not Found) API error. This indicates that the requested resource could not be found on the server.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/report-endpoints.md#_snippet_24

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "404"
}
```

----------------------------------------

TITLE: Get All Known Malware Kits (Rapid7 InsightVM API)
DESCRIPTION: Documents the API endpoint to retrieve a paginated list of all known malware kits. It supports query parameters for pagination (page, size) and sorting, and provides examples of successful and error responses. Request and response content types are JSON.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/vulnerability-endpoints.md#_snippet_4

LANGUAGE: APIDOC
CODE:
```
Endpoint: GET /api/3/malware_kits
Description: Returns all known malware kits.
Operation ID: getMalwareKits

Request Content-Type: application/json
Response Content-Type: application/json;charset=UTF-8

Parameters:
  - Name: page
    Location: query
    Type: integer
    Required: No
    Description: The index of the page (zero-based) to retrieve.
  - Name: size
    Location: query
    Type: integer
    Required: No
    Description: The number of records per page to retrieve.
  - Name: sort
    Location: query
    Type: array
    Required: No
    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.

Responses:
  - Status: 200
    Description: OK
    Schema: PageOf«MalwareKit»
  - Status: 401
    Description: Unauthorized
    Schema: UnauthorizedError
  - Status: 404
    Description: Not Found
    Schema: NotFoundError
  - Status: 500
    Description: Internal Server Error
    Schema: InternalServerError
  - Status: 503
    Description: Service Unavailable
    Schema: ServiceUnavailableError
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "page": {
    "number": 6,
    "size": 10,
    "totalPages": 13,
    "totalResources": 123
  },
  "resources": [
    {
      "id": 152,
      "links": [
        {
          "href": "https://hostname:3780/api/3/...",
          "rel": "self"
        }
      ],
      "name": "Alpha Pack",
      "popularity": "Rare"
    }
  ]
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "401"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "404"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "500"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "503"
}
```

----------------------------------------

TITLE: Retrieve Specific Policy Details (GET /api/3/policies/{policyId})
DESCRIPTION: Documents the `GET /api/3/policies/{policyId}` endpoint, which retrieves details for a specified policy. It outlines the required path parameter `policyId` and provides example JSON responses for various HTTP status codes, including a successful `Policy` object.

SOURCE: https://github.com/riza/rapid7-insightvm-api-docs/blob/main/policy-endpoints.md#_snippet_22

LANGUAGE: APIDOC
CODE:
```
Endpoint: GET /api/3/policies/{policyId}
Description: Retrieves the specified policy.
Operation ID: getPolicy

Parameters:
  Name: policyId
  Location: path
  Type: integer
  Required: Yes
  Description: The identifier of the policy

Responses:
  200 OK:
    Description: OK
    Schema: Policy
  401 Unauthorized:
    Description: Unauthorized
    Schema: UnauthorizedError
  404 Not Found:
    Description: Not Found
    Schema: NotFoundError
  500 Internal Server Error:
    Description: Internal Server Error
    Schema: InternalServerError
  503 Service Unavailable:
    Description: Service Unavailable
    Schema: ServiceUnavailableError

Request Content-Type: application/json
Response Content-Type: application/json;charset=UTF-8
```

LANGUAGE: json
CODE:
```
{
  "enabled": [
    42
  ],
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "recursiveWindowsFSSearch": false,
  "storeSCAP": false
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "401"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "404"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "500"
}
```

LANGUAGE: json
CODE:
```
{
  "links": [
    {
      "href": "https://hostname:3780/api/3/...",
      "rel": "self"
    }
  ],
  "message": "An error has occurred.",
  "status": "503"
}
```