{ "aid": "rapid7.com:main-3", "name": "Rapid7 VM API", "type": "Index", "description": "# Overview \n\nThis guide documents the Rapid7 VM Application Programming Interface (API) Version 3. This API supports the\nRepresentation State Transfer (REST) design pattern. Unless noted otherwise this API accepts and produces the\n`application/json` media type. This API uses Hypermedia as the Engine of Application State (HATEOAS) and\nis hypermedia friendly. All API connections must be made to the security console using HTTPS.\n\n## Versioning\n\nVersioning is specified in the URL and the base path of this API is: `https://:/api/3/`.\n\n## Specification\n\nAn OpenAPI v3.1.0 specification (also \nknown as Swagger) of this API is available. Tools such as swagger-codegen\ncan be used to generate an API client in the language of your choosing using this specification document.\n\n## Authentication\n\nAuthorization to the API uses HTTP Basic Authorization \n(see RFC 2617 for more information). Requests must \nsupply authorization credentials in the `Authorization` header using a Base64 encoded hash of `\"username:password\"`.\n\n\n\n### 2FA\n\nThis API supports two-factor authentication (2FA) by supplying an authentication token in addition to the Basic\nAuthorization. The token is specified using the `Token` request header. To leverage two-factor authentication, this\nmust be enabled on the console and be configured for the account accessing the API.\n\n## Resources\n\n### Naming\n\nResource names represent nouns and identify the entity being manipulated or accessed. All collection resources are \npluralized to indicate to the client they are interacting with a collection of multiple resources of the same type.\nSingular resource names are used when there exists only one resource available to interact with.\n\nThe following naming conventions are used by this API:\n\n| Type | Case |\n| --------------------------------------------- | ------------------------ |\n| Resource names | `lower_snake_case` |\n| Header, body, and query parameters parameters | `camelCase` |\n| JSON fields and property names | `camelCase` |\n\n#### Collections\n\nA collection resource is a parent resource for instance resources, but can itself be retrieved and operated on \nindependently. Collection resources use a pluralized resource name. The resource path for collection resources follow \nthe convention:\n\n```\n/api/3/{resource_name}\n```\n\n#### Instances\n\nAn instance resource is a \"leaf\" level resource that may be retrieved, optionally nested within a collection resource.\nInstance resources are usually retrievable with opaque identifiers. The resource path for instance resources follows \nthe convention:\n\n```\n/api/3/{resource_name}/{instance_id}...\n```\n\n## Verbs\n\nThe following HTTP operations are supported throughout this API. The general usage of the operation and both\nits failure and success status codes are outlined below. \n \n| Verb | Usage | Success | Failure |\n| --------- | ------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- |\n| `GET` | Used to retrieve a resource by identifier, or a collection of resources by type. | `200` | `400`, `401`, `402`, `404`, `405`, `408`, `410`, `415`, `500` |\n| `POST` | Creates a resource with an application-specified identifier. | `201` | `400`, `401`, `404`, `405`, `408`, `413`, `415`, `500` |\n| `POST` | Performs a request to queue an asynchronous job. | `202` | `400`, `401`, `405`, `408`, `410`, `413`, `415`, `500` |\n| `PUT` | Creates a resource with a client-specified identifier. | `200` | `400`, `401`, `403`, `405`, `408`, `410`, `413`, `415`, `500` |\n| `PUT` | Performs a full update of a resource with a specified identifier. | `201` | `400`, `401`, `403`, `405`, `408`, `410`, `413`, `415`, `500` |\n| `DELETE` | Deletes a resource by identifier or an entire collection of resources. | `204` | `400`, `401`, `405`, `408`, `410`, `413`, `415`, `500` |\n| `OPTIONS` | Requests what operations are available on a resource. | `200` | `401`, `404`, `405`, `408`, `500` |\n\n### Common Operations\n\n#### OPTIONS\n\nAll resources respond to the `OPTIONS` request, which allows discoverability of available operations that are supported. \nThe `OPTIONS` response returns the acceptable HTTP operations on that resource within the `Allow` header. The response\nis always a `200 OK` status.\n\n### Collection Resources\n\nCollection resources can support the `GET`, `POST`, `PUT`, and `DELETE` operations.\n\n#### GET\n\nThe `GET` operation invoked on a collection resource indicates a request to retrieve all, or some, of the entities \ncontained within the collection. This also includes the optional capability to filter or search resources during\nthe request. The response from a collection listing is a paginated document. See \n[hypermedia links](#section/Overview/Paging) for more information.\n\n#### POST\n\nThe `POST` is a non-idempotent operation that allows for the creation of a new resource when the resource identifier \nis not provided by the system during the creation operation (i.e. the Security Console generates the identifier). The\ncontent of the `POST` request is sent in the request body. The response to a successful `POST` request should be a \n`201 CREATED` with a valid `Location` header field set to the URI that can be used to access to the newly \ncreated resource. \n\nThe `POST` to a collection resource can also be used to interact with asynchronous resources. In this situation, \ninstead of a `201 CREATED` response, the `202 ACCEPTED` response indicates that processing of the request is not fully \ncomplete but has been accepted for future processing. This request will respond similarly with a `Location` header with \nlink to the job-oriented asynchronous resource that was created and/or queued.\n\n#### PUT\n\nThe `PUT` is an idempotent operation that either performs a create with user-supplied identity, or a full replace\nor update of a resource by a known identifier. The response to a `PUT` operation to create an entity is a `201 Created`\nwith a valid `Location` header field set to the URI that can be used to access to the newly created resource.\n\n`PUT` on a collection resource replaces all values in the collection. The typical response to a `PUT` operation that \nupdates an entity is hypermedia links, which may link to related resources caused by the side-effects of the changes \nperformed.\n\n#### DELETE\n\nThe `DELETE` is an idempotent operation that physically deletes a resource, or removes an association between resources.\nThe typical response to a `DELETE` operation is hypermedia links, which may link to related resources caused by the \nside-effects of the changes performed.\n\n### Instance Resources\n\nInstance resources can support the `GET`, `PUT`, `POST`, `PATCH` and `DELETE` operations.\n\n#### GET\n\nRetrieves the details of a specific resource by its identifier. The details retrieved can be controlled through \nproperty selection and property views. The content of the resource is returned within the body of the response in the \nacceptable media type. \n\n#### PUT\n\nAllows for and idempotent \"full update\" (complete replacement) on a specific resource. If the resource does not exist, \nit will be created; if it does exist, it is completely overwritten. Any omitted properties in the request are assumed to \nbe undefined/null. For \"partial updates\" use `POST` or `PATCH` instead. \n\nThe content of the `PUT` request is sent in the request body. The identifier of the resource is specified within the URL \n(not the request body). The response to a successful `PUT` request is a `201 CREATED` to represent the created status, \nwith a valid `Location` header field set to the URI that can be used to access to the newly created (or fully replaced) \nresource. \n\n#### POST\n\nPerforms a non-idempotent creation of a new resource. The `POST` of an instance resource most commonly occurs with the \nuse of nested resources (e.g. searching on a parent collection resource). The response to a `POST` of an instance \nresource is typically a `200 OK` if the resource is non-persistent, and a `201 CREATED` if there is a resource \ncreated/persisted as a result of the operation. This varies by endpoint.\n\n#### PATCH\n\nThe `PATCH` operation is used to perform a partial update of a resource. `PATCH` is a non-idempotent operation that\nenforces an atomic mutation of a resource. Only the properties specified in the request are to be overwritten on the \nresource it is applied to. If a property is missing, it is assumed to not have changed.\n\n#### DELETE\n\nPermanently removes the individual resource from the system. If the resource is an association between resources, only \nthe association is removed, not the resources themselves. A successful deletion of the resource should return \n`204 NO CONTENT` with no response body. This operation is not fully idempotent, as follow-up requests to delete a \nnon-existent resource should return a `404 NOT FOUND`.\n\n## Requests\n\nUnless otherwise indicated, the default request body media type is `application/json`.\n\n### Headers\n\nCommonly used request headers include:\n\n| Header | Example | Purpose | \n| ------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `Accept` | `application/json` | Defines what acceptable content types are allowed by the client. For all types, use `*/*`. |\n| `Accept-Encoding` | `deflate, gzip` | Allows for the encoding to be specified (such as gzip). |\n| `Accept-Language` | `en-US` | Indicates to the server the client's locale (defaults `en-US`). |\n| `Authorization ` | `Basic Base64(\"username:password\")` | Basic authentication |\n| `Token ` | `123456` | Two-factor authentication token (if enabled) |\n\n### Dates & Times\n\nDates and/or times are specified as strings in the ISO 8601 format(s). The following formats are supported as input:\n\n| Value | Format | Notes |\n| --------------------------- | ------------------------------------------------------ | ----------------------------------------------------- |\n| Date | YYYY-MM-DD | Defaults to 12 am UTC (if used for a date & time |\n| Date & time only | YYYY-MM-DD'T'hh:mm:ss[.nnn] | Defaults to UTC |\n| Date & time in UTC | YYYY-MM-DD'T'hh:mm:ss[.nnn]Z | |\n| Date & time w/ offset | YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm | |\n| Date & time w/ zone-offset | YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm[] | |\n \n### Timezones\n\nTimezones are specified in the regional zone format, such as `\"America/Los_Angeles\"`, `\"Asia/Tokyo\"`, or `\"GMT\"`.\n \n### Paging\n\nPagination is supported on certain collection resources using a combination of two query parameters, `page` and `size`. \nAs these are control parameters, they are prefixed with the underscore character. The page parameter dictates the \nzero-based index of the page to retrieve, and the `size` indicates the size of the page. \n\nFor example, `/resources?page=2&size=10` will return page 3, with 10 records per page, giving results 21-30.\n\nThe maximum page size for a request is 500.\n\n### Sorting\n\nSorting is supported on paginated resources with the `sort` query parameter(s). The sort query parameter(s) supports \nidentifying a single or multi-property sort with a single or multi-direction output. The format of the parameter is:\n\n```\nsort=property[,ASC|DESC]...\n```\n\nTherefore, the request `/resources?sort=name,title,DESC` would return the results sorted by the name and title \ndescending, in that order. The sort directions are either ascending `ASC` or descending `DESC`. With single-order \nsorting, all properties are sorted in the same direction. To sort the results with varying orders by property,\n multiple sort parameters are passed. \n \nFor example, the request `/resources?sort=name,ASC&sort=title,DESC` would sort by name ascending and title \ndescending, in that order.\n\n## Responses\n\nThe following response statuses may be returned by this API.\n \n| Status | Meaning | Usage |\n| ------ | ------------------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `200` | OK | The operation performed without error according to the specification of the request, and no more specific 2xx code is suitable. |\n| `201` | Created | A create request has been fulfilled and a resource has been created. The resource is available as the URI specified in the response, including the `Location` header. |\n| `202` | Accepted | An asynchronous task has been accepted, but not guaranteed, to be processed in the future. |\n| `400` | Bad Request | The request was invalid or cannot be otherwise served. The request is not likely to succeed in the future without modifications. |\n| `401` | Unauthorized | The user is unauthorized to perform the operation requested, or does not maintain permissions to perform the operation on the resource specified. |\n| `403` | Forbidden | The resource exists to which the user has access, but the operating requested is not permitted. |\n| `404` | Not Found | The resource specified could not be located, does not exist, or an unauthenticated client does not have permissions to a resource. |\n| `405` | Method Not Allowed | The operations may not be performed on the specific resource. Allowed operations are returned and may be performed on the resource. |\n| `408` | Request Timeout | The client has failed to complete a request in a timely manner and the request has been discarded. |\n| `413` | Request Entity Too Large | The request being provided is too large for the server to accept processing. |\n| `415` | Unsupported Media Type | The media type is not supported for the requested resource. |\n| `500` | Internal Server Error | An internal and unexpected error has occurred on the server at no fault of the client. |\n\n### Security\n\nThe response statuses 401, 403 and 404 need special consideration for security purposes. As necessary, \nerror statuses and messages may be obscured to strengthen security and prevent information exposure. The following is a \nguideline for privileged resource response statuses:\n\n| Use Case | Access | Resource | Permission | Status |\n| ------------------------------------------------------------------ | ------------------ |------------------- | ------------ | ------------ |\n| Unauthenticated access to an unauthenticated resource. | Unauthenticated | Unauthenticated | Yes | `20x` |\n| Unauthenticated access to an authenticated resource. | Unauthenticated | Authenticated | No | `401` |\n| Unauthenticated access to an authenticated resource. | Unauthenticated | Non-existent | No | `401` |\n| Authenticated access to a unauthenticated resource. | Authenticated | Unauthenticated | Yes | `20x` |\n| Authenticated access to an authenticated, unprivileged resource. | Authenticated | Authenticated | No | `404` |\n| Authenticated access to an authenticated, privileged resource. | Authenticated | Authenticated | Yes | `20x` |\n| Authenticated access to an authenticated, non-existent resource | Authenticated | Non-existent | Yes | `404` |\n\n### Headers\n\nCommonly used response headers include:\n\n| Header | Example | Purpose |\n| -------------------------- | --------------------------------- | --------------------------------------------------------------- |\n| `Allow` | `OPTIONS, GET` | Defines the allowable HTTP operations on a resource. |\n| `Cache-Control` | `no-store, must-revalidate` | Disables caching of resources (as they are all dynamic). |\n| `Content-Encoding` | `gzip` | The encoding of the response body (if any). |\n| `Location` | | Refers to the URI of the resource created by a request. |\n| `Transfer-Encoding` | `chunked` | Specified the encoding used to transform response. |\n| `Retry-After` | 5000 | Indicates the time to wait before retrying a request. |\n| `X-Content-Type-Options` | `nosniff` | Disables MIME type sniffing. |\n| `X-XSS-Protection` | `1; mode=block` | Enables XSS filter protection. |\n| `X-Frame-Options` | `SAMEORIGIN` | Prevents rendering in a frame from a different origin. |\n| `X-UA-Compatible` | `IE=edge,chrome=1` | Specifies the browser mode to render in. |\n\n### Format\n\nWhen `application/json` is returned in the response body it is always pretty-printed (indented, human readable output). \nAdditionally, gzip compression/encoding is supported on all responses. \n\n#### Dates & Times\n\nDates or times are returned as strings in the ISO 8601 'extended' format. When a date and time is returned (instant) the value is converted to UTC.\n\nFor example:\n\n| Value | Format | Example |\n| --------------- | ------------------------------ | --------------------- |\n| Date | `YYYY-MM-DD` | 2017-12-03 |\n| Date & Time | `YYYY-MM-DD'T'hh:mm:ss[.nnn]Z` | 2017-12-03T10:15:30Z |\n\n#### Content\n\nIn some resources a Content data type is used. This allows for multiple formats of representation to be returned\nwithin resource, specifically `\"html\"` and `\"text\"`. The `\"text\"` property returns a flattened representation suitable\nfor output in textual displays. The `\"html\"` property returns an HTML fragment suitable for display within an HTML \nelement. Note, the HTML returned is not a valid stand-alone HTML document.\n\n#### Paging\n\nThe response to a paginated request follows the format:\n\n```json\n{\n resources\": [ \n ... \n ],\n \"page\": { \n \"number\" : ...,\n \"size\" : ...,\n \"totalResources\" : ...,\n \"totalPages\" : ...\n },\n \"links\": [ \n \"first\" : {\n \"href\" : \"...\"\n },\n \"prev\" : {\n \"href\" : \"...\"\n },\n \"self\" : {\n \"href\" : \"...\"\n },\n \"next\" : {\n \"href\" : \"...\"\n },\n \"last\" : {\n \"href\" : \"...\"\n } \n ]\n}\n```\n\nThe `resources` property is an array of the resources being retrieved from the endpoint, each which should contain at \nminimum a \"self\" relation hypermedia link. The `page` property outlines the details of the current page and total\npossible pages. The object for the page includes the following properties:\n\n- number - The page number (zero-based) of the page returned.\n- size - The size of the pages, which is less than or equal to the maximum page size.\n- totalResources - The total amount of resources available across all pages.\n- totalPages - The total amount of pages.\n\nThe last property of the paged response is the `links` array, which contains all available hypermedia links. For \npaginated responses, the \"self\", \"next\", \"previous\", \"first\", and \"last\" links are returned. The \"self\" link must\nalways be returned and should contain a link to allow the client to replicate the original request against the \ncollection resource in an identical manner to that in which it was invoked. \n\nThe \"next\" and \"previous\" links are present if either or both there exists a previous or next page, respectively. \nThe \"next\" and \"previous\" links have hrefs that allow \"natural movement\" to the next page, that is all parameters \nrequired to move the next page are provided in the link. The \"first\" and \"last\" links provide references to the first\nand last pages respectively. \n\nRequests outside the boundaries of the pageable will result in a `404 NOT FOUND`. Paginated requests do not provide a \n\"stateful cursor\" to the client, nor does it need to provide a read consistent view. Records in adjacent pages may \nchange while pagination is being traversed, and the total number of pages and resources may change between requests \nwithin the same filtered/queries resource collection.\n\n#### Property Views\n\nThe \"depth\" of the response of a resource can be configured using a \"view\". All endpoints supports two views that can \ntune the extent of the information returned in the resource. The supported views are `summary` and `details` (the default). \nView are specified using a query parameter, in this format:\n\n```bash\n/?view={viewName}\n```\n\n#### Error\n\nAny error responses can provide a response body with a message to the client indicating more information (if applicable) \nto aid debugging of the error. All 40x and 50x responses will return an error response in the body. The format of the \nresponse is as follows:\n\n```json\n{\n \"status\": ,\n \"message\": ,\n \"links\" : [ {\n \"rel\" : \"...\",\n \"href\" : \"...\"\n } ]\n} \n ```\n \nThe `status` property is the same as the HTTP status returned in the response, to ease client parsing. The message \nproperty is a localized message in the request client's locale (if applicable) that articulates the nature of the \nerror. The last property is the `links` property. This may contain additional \n[hypermedia links](#section/Overview/Authentication) to troubleshoot.\n\n#### Search Criteria \n\nMultiple resources make use of search criteria to match assets. Search criteria is an array of search filters. Each \nsearch filter has a generic format of:\n\n```json\n{ \n \"field\": \"\", \n \"operator\": \"\", \n [\"value\": ,]\n [\"lower\": ,]\n [\"upper\": ]\n}\n \n```\n\nEvery filter defines two required properties `field` and `operator`. The field is the name of an asset property that\nis being filtered on. The operator is a type and property-specific operating performed on the filtered property. The\nvalid values for fields and operators are outlined in the table below. Depending on the data type of the operator\nthe value may be a numeric or string format.\n\nEvery filter also defines one or more values that are supplied to the operator. The valid values vary by operator\nand are outlined below.\n\n##### Fields\n\nThe following table outlines the search criteria fields and the available operators:\n\n| Field | Operators |\n| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `alternate-address-type` | `in` |\n| `container-image` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-like` `not-like` |\n| `container-status` | `is` `is-not` |\n| `containers` | `are` |\n| `criticality-tag` | `is` `is-not` `is-greater-than` `is-less-than` `is-applied` ` is-not-applied` |\n| `custom-tag` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-applied` `is-not-applied` |\n| `cve` | `is` `is-not` `contains` `does-not-contain` |\n| `cvss-access-complexity` | `is` `is-not` |\n| `cvss-authentication-required` | `is` `is-not` |\n| `cvss-access-vector` | `is` `is-not` |\n| `cvss-availability-impact` | `is` `is-not` |\n| `cvss-confidentiality-impact` | `is` `is-not` |\n| `cvss-integrity-impact` | `is` `is-not` |\n| `cvss-v3-confidentiality-impact` | `is` `is-not` |\n| `cvss-v3-integrity-impact` | `is` `is-not` |\n| `cvss-v3-availability-impact` | `is` `is-not` |\n| `cvss-v3-attack-vector` | `is` `is-not` |\n| `cvss-v3-attack-complexity` | `is` `is-not` |\n| `cvss-v3-user-interaction` | `is` `is-not` |\n| `cvss-v3-privileges-required` | `is` `is-not` |\n| `host-name` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-empty` `is-not-empty` `is-like` `not-like` |\n| `host-type` | `in` `not-in` |\n| `ip-address` | `is` `is-not` `in-range` `not-in-range` `is-like` `not-like` |\n| `ip-address-type` | `in` `not-in` |\n| `last-scan-date` | `is-on-or-before` `is-on-or-after` `is-between` `is-earlier-than` `is-within-the-last` |\n| `location-tag` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-applied` `is-not-applied` |\n| `mobile-device-last-sync-time` | `is-within-the-last` `is-earlier-than` |\n| `open-ports` | `is` `is-not` ` in-range` |\n| `operating-system` | `contains` ` does-not-contain` ` is-empty` ` is-not-empty` |\n| `owner-tag` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-applied` `is-not-applied` |\n| `pci-compliance` | `is` |\n| `risk-score` | `is` `is-not` `is-greater-than` `is-less-than` `in-range` |\n| `service-name` | `contains` `does-not-contain` |\n| `site-id` | `in` `not-in` |\n| `software` | `contains` `does-not-contain` |\n| `vAsset-cluster` | `is` `is-not` `contains` `does-not-contain` `starts-with` |\n| `vAsset-datacenter` | `is` `is-not` |\n| `vAsset-host-name` | `is` `is-not` `contains` `does-not-contain` `starts-with` |\n| `vAsset-power-state` | `in` `not-in` |\n| `vAsset-resource-pool-path` | `contains` `does-not-contain` |\n| `vulnerability-assessed` | `is-on-or-before` `is-on-or-after` `is-between` `is-earlier-than` `is-within-the-last` |\n| `vulnerability-category` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` |\n| `vulnerability-cvss-v3-score` | `is` `is-not` |\n| `vulnerability-cvss-score` | `is` `is-not` `in-range` `is-greater-than` `is-less-than` |\n| `vulnerability-exposures` | `includes` `does-not-include` |\n| `vulnerability-title` | `contains` `does-not-contain` `is` `is-not` `starts-with` `ends-with` |\n| `vulnerability-validated-status` | `are` |\n\n##### Enumerated Properties\n\nThe following fields have enumerated values:\n\n| Field | Acceptable Values |\n| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| `alternate-address-type` | 0=IPv4, 1=IPv6 |\n| `containers` | 0=present, 1=not present |\n| `container-status` | `created` `running` `paused` `restarting` `exited` `dead` `unknown` |\n| `cvss-access-complexity` |
  • L = Low
  • M = Medium
  • H = High
|\n| `cvss-integrity-impact` |
  • N = None
  • P = Partial
  • C = Complete
|\n| `cvss-confidentiality-impact` |
  • N = None
  • P = Partial
  • C = Complete
|\n| `cvss-availability-impact` |
  • N = None
  • P = Partial
  • C = Complete
|\n| `cvss-access-vector` |
  • L = Local
  • A = Adjacent
  • N = Network
|\n| `cvss-authentication-required` |
  • N = None
  • S = Single
  • M = Multiple
|\n| `cvss-v3-confidentiality-impact` |
  • L = Local
  • L = Low
  • N = None
  • H = High
|\n| `cvss-v3-integrity-impact` |
  • L = Local
  • L = Low
  • N = None
  • H = High
|\n| `cvss-v3-availability-impact` |
  • N = None
  • L = Low
  • H = High
|\n| `cvss-v3-attack-vector` |
  • N = Network
  • A = Adjacent
  • L = Local
  • P = Physical
|\n| `cvss-v3-attack-complexity` |
  • L = Low
  • H = High
|\n| `cvss-v3-user-interaction` |
  • N = None
  • R = Required
|\n| `cvss-v3-privileges-required` |
  • N = None
  • L = Low
  • H = High
|\n| `host-type` | 0=Unknown, 1=Guest, 2=Hypervisor, 3=Physical, 4=Mobile |\n| `ip-address-type` | 0=IPv4, 1=IPv6 |\n| `pci-compliance` | 0=fail, 1=pass |\n| `vulnerability-validated-status` | 0=present, 1=not present |\n\n##### Operator Properties \n\nThe following table outlines which properties are required for each operator and the appropriate data type(s):\n\n| Operator | `value` | `lower` | `upper` |\n| ----------------------|-----------------------|-----------------------|------------------------|\n| `are` | `string` | | |\n| `contains` | `string` | | |\n| `does-not-contain` | `string` | | |\n| `ends with` | `string` | | |\n| `in` | `Array[ string ]` | | |\n| `in-range` | | `numeric` | `numeric` |\n| `includes` | `Array[ string ]` | | |\n| `is` | `string` | | |\n| `is-applied` | | | |\n| `is-between` | | `string` (yyyy-MM-dd) | `numeric` (yyyy-MM-dd) |\n| `is-earlier-than` | `numeric` (days) | | |\n| `is-empty` | | | |\n| `is-greater-than` | `numeric` | | |\n| `is-on-or-after` | `string` (yyyy-MM-dd) | | |\n| `is-on-or-before` | `string` (yyyy-MM-dd) | | |\n| `is-not` | `string` | | |\n| `is-not-applied` | | | |\n| `is-not-empty` | | | |\n| `is-within-the-last` | `numeric` (days) | | |\n| `less-than` | `string` | | | \n| `like` | `string` | | |\n| `not-contains` | `string` | | |\n| `not-in` | `Array[ string ]` | | |\n| `not-in-range` | | `numeric` | `numeric` |\n| `not-like` | `string` | | |\n| `starts-with` | `string` | | |\n\n#### Discovery Connection Search Criteria \n\nDynamic sites make use of search criteria to match assets from a discovery connection. Search criteria is an array of search filters. \n\nEach search filter has a generic format of:\n\n```json\n{ \n \"field\": \"\", \n \"operator\": \"\", \n [\"value\": \"\",]\n [\"lower\": \"\",]\n [\"upper\": \"\"]\n}\n \n```\n\nEvery filter defines two required properties `field` and `operator`. The field is the name of an asset property that\nis being filtered on. The list of supported fields vary depending on the type of discovery connection configured \nfor the dynamic site (e.g vSphere, ActiveSync, etc.). The operator is a type and property-specific operating \nperformed on the filtered property. The valid values for fields outlined in the tables below and are grouped by the \ntype of connection. \n\nEvery filter also defines one or more values that are supplied to the operator. See \nSearch Criteria Operator Properties for more \ninformation on the valid values for each operator. \n\n##### Fields (ActiveSync)\n\nThis section documents search criteria information for ActiveSync discovery connections. The discovery connections \nmust be one of the following types: `\"activesync-ldap\"`, `\"activesync-office365\"`, or `\"activesync-powershell\"`. \n\nThe following table outlines the search criteria fields and the available operators for ActiveSync connections:\n\n| Field | Operators |\n| --------------------------------- | ------------------------------------------------------------- |\n| `last-sync-time` | `is-within-the-last` ` is-earlier-than` |\n| `operating-system` | `contains` ` does-not-contain` |\n| `user` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n\n##### Fields (AWS)\n\nThis section documents search criteria information for AWS discovery connections. The discovery connections must be the type `\"aws\"`. \n\nThe following table outlines the search criteria fields and the available operators for AWS connections:\n\n| Field | Operators |\n| ----------------------- | ------------------------------------------------------------- |\n| `availability-zone` | `contains` ` does-not-contain` |\n| `guest-os-family` | `contains` ` does-not-contain` |\n| `instance-id` | `contains` ` does-not-contain` |\n| `instance-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n| `instance-state` | `in` ` not-in` |\n| `instance-type` | `in` ` not-in` |\n| `ip-address` | `in-range` ` not-in-range` ` is` ` is-not` |\n| `region` | `in` ` not-in` |\n| `vpc-id` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n\n##### Fields (DHCP)\n\nThis section documents search criteria information for DHCP discovery connections. The discovery connections must be the type `\"dhcp\"`. \n\nThe following table outlines the search criteria fields and the available operators for DHCP connections:\n\n| Field | Operators |\n| --------------- | ------------------------------------------------------------- |\n| `host-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n| `ip-address` | `in-range` ` not-in-range` ` is` ` is-not` |\n| `mac-address` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n\n##### Fields (Sonar)\n\nThis section documents search criteria information for Sonar discovery connections. The discovery connections must be the type `\"sonar\"`. \n\nThe following table outlines the search criteria fields and the available operators for Sonar connections:\n\n| Field | Operators |\n| ------------------- | -------------------- |\n| `search-domain` | `contains` ` is` |\n| `ip-address` | `in-range` ` is` |\n| `sonar-scan-date` | `is-within-the-last` |\n\n##### Fields (vSphere)\n\nThis section documents search criteria information for vSphere discovery connections. The discovery connections must be the type `\"vsphere\"`. \n\nThe following table outlines the search criteria fields and the available operators for vSphere connections:\n\n| Field | Operators |\n| -------------------- | ------------------------------------------------------------------------------------------ |\n| `cluster` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n| `data-center` | `is` ` is-not` |\n| `discovered-time` | `is-on-or-before` ` is-on-or-after` ` is-between` ` is-earlier-than` ` is-within-the-last` |\n| `guest-os-family` | `contains` ` does-not-contain` |\n| `host-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n| `ip-address` | `in-range` ` not-in-range` ` is` ` is-not` |\n| `power-state` | `in` ` not-in` |\n| `resource-pool-path` | `contains` ` does-not-contain` |\n| `last-time-seen` | `is-on-or-before` ` is-on-or-after` ` is-between` ` is-earlier-than` ` is-within-the-last` |\n| `vm` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n\n##### Enumerated Properties (vSphere)\n\nThe following fields have enumerated values:\n\n| Field | Acceptable Values |\n| ------------- | ------------------------------------ |\n| `power-state` | `poweredOn` `poweredOff` `suspended` |\n\n## HATEOAS\n\nThis API follows Hypermedia as the Engine of Application State (HATEOAS) principals and is therefore hypermedia friendly. \nHyperlinks are returned in the `links` property of any given resource and contain a fully-qualified hyperlink to\nthe corresponding resource. The format of the hypermedia link adheres to both the\n{json:api} v1 \n\"Link Object\" and \nJSON Hyper-Schema \n\"Link Description Object\"\nformats. For example:\n\n```json\n\"links\": [{\n \"rel\": \"\",\n \"href\": \"\"\n ...\n}]\n```\n\nWhere appropriate link objects may also contain additional properties than the `rel` and `href` properties, such as `id`, `type`, etc.\n\nSee the [Root](#tag/Root) resources for the entry points into API discovery.\n", "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/rapid7.com/main/3/apis.json", "tags": [ "rapid7.com", "main" ], "created": "2026-04-11", "modified": "2026-04-11", "specificationVersion": "0.19", "access": "3rd-Party", "maintainers": [ { "FN": "Jentic", "X-github": "jentic", "url": "https://github.com/jentic" } ], "apis": [ { "aid": "rapid7.com:main-3", "name": "Rapid7 VM API", "description": "# Overview \n\nThis guide documents the Rapid7 VM Application Programming Interface (API) Version 3. This API supports the\nRepresentation State Transfer (REST) design pattern. Unless noted otherwise this API accepts and produces the\n`application/json` media type. This API uses Hypermedia as the Engine of Application State (HATEOAS) and\nis hypermedia friendly. All API connections must be made to the security console using HTTPS.\n\n## Versioning\n\nVersioning is specified in the URL and the base path of this API is: `https://:/api/3/`.\n\n## Specification\n\nAn OpenAPI v3.1.0 specification (also \nknown as Swagger) of this API is available. Tools such as swagger-codegen\ncan be used to generate an API client in the language of your choosing using this specification document.\n\n## Authentication\n\nAuthorization to the API uses HTTP Basic Authorization \n(see RFC 2617 for more information). Requests must \nsupply authorization credentials in the `Authorization` header using a Base64 encoded hash of `\"username:password\"`.\n\n\n\n### 2FA\n\nThis API supports two-factor authentication (2FA) by supplying an authentication token in addition to the Basic\nAuthorization. The token is specified using the `Token` request header. To leverage two-factor authentication, this\nmust be enabled on the console and be configured for the account accessing the API.\n\n## Resources\n\n### Naming\n\nResource names represent nouns and identify the entity being manipulated or accessed. All collection resources are \npluralized to indicate to the client they are interacting with a collection of multiple resources of the same type.\nSingular resource names are used when there exists only one resource available to interact with.\n\nThe following naming conventions are used by this API:\n\n| Type | Case |\n| --------------------------------------------- | ------------------------ |\n| Resource names | `lower_snake_case` |\n| Header, body, and query parameters parameters | `camelCase` |\n| JSON fields and property names | `camelCase` |\n\n#### Collections\n\nA collection resource is a parent resource for instance resources, but can itself be retrieved and operated on \nindependently. Collection resources use a pluralized resource name. The resource path for collection resources follow \nthe convention:\n\n```\n/api/3/{resource_name}\n```\n\n#### Instances\n\nAn instance resource is a \"leaf\" level resource that may be retrieved, optionally nested within a collection resource.\nInstance resources are usually retrievable with opaque identifiers. The resource path for instance resources follows \nthe convention:\n\n```\n/api/3/{resource_name}/{instance_id}...\n```\n\n## Verbs\n\nThe following HTTP operations are supported throughout this API. The general usage of the operation and both\nits failure and success status codes are outlined below. \n \n| Verb | Usage | Success | Failure |\n| --------- | ------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- |\n| `GET` | Used to retrieve a resource by identifier, or a collection of resources by type. | `200` | `400`, `401`, `402`, `404`, `405`, `408`, `410`, `415`, `500` |\n| `POST` | Creates a resource with an application-specified identifier. | `201` | `400`, `401`, `404`, `405`, `408`, `413`, `415`, `500` |\n| `POST` | Performs a request to queue an asynchronous job. | `202` | `400`, `401`, `405`, `408`, `410`, `413`, `415`, `500` |\n| `PUT` | Creates a resource with a client-specified identifier. | `200` | `400`, `401`, `403`, `405`, `408`, `410`, `413`, `415`, `500` |\n| `PUT` | Performs a full update of a resource with a specified identifier. | `201` | `400`, `401`, `403`, `405`, `408`, `410`, `413`, `415`, `500` |\n| `DELETE` | Deletes a resource by identifier or an entire collection of resources. | `204` | `400`, `401`, `405`, `408`, `410`, `413`, `415`, `500` |\n| `OPTIONS` | Requests what operations are available on a resource. | `200` | `401`, `404`, `405`, `408`, `500` |\n\n### Common Operations\n\n#### OPTIONS\n\nAll resources respond to the `OPTIONS` request, which allows discoverability of available operations that are supported. \nThe `OPTIONS` response returns the acceptable HTTP operations on that resource within the `Allow` header. The response\nis always a `200 OK` status.\n\n### Collection Resources\n\nCollection resources can support the `GET`, `POST`, `PUT`, and `DELETE` operations.\n\n#### GET\n\nThe `GET` operation invoked on a collection resource indicates a request to retrieve all, or some, of the entities \ncontained within the collection. This also includes the optional capability to filter or search resources during\nthe request. The response from a collection listing is a paginated document. See \n[hypermedia links](#section/Overview/Paging) for more information.\n\n#### POST\n\nThe `POST` is a non-idempotent operation that allows for the creation of a new resource when the resource identifier \nis not provided by the system during the creation operation (i.e. the Security Console generates the identifier). The\ncontent of the `POST` request is sent in the request body. The response to a successful `POST` request should be a \n`201 CREATED` with a valid `Location` header field set to the URI that can be used to access to the newly \ncreated resource. \n\nThe `POST` to a collection resource can also be used to interact with asynchronous resources. In this situation, \ninstead of a `201 CREATED` response, the `202 ACCEPTED` response indicates that processing of the request is not fully \ncomplete but has been accepted for future processing. This request will respond similarly with a `Location` header with \nlink to the job-oriented asynchronous resource that was created and/or queued.\n\n#### PUT\n\nThe `PUT` is an idempotent operation that either performs a create with user-supplied identity, or a full replace\nor update of a resource by a known identifier. The response to a `PUT` operation to create an entity is a `201 Created`\nwith a valid `Location` header field set to the URI that can be used to access to the newly created resource.\n\n`PUT` on a collection resource replaces all values in the collection. The typical response to a `PUT` operation that \nupdates an entity is hypermedia links, which may link to related resources caused by the side-effects of the changes \nperformed.\n\n#### DELETE\n\nThe `DELETE` is an idempotent operation that physically deletes a resource, or removes an association between resources.\nThe typical response to a `DELETE` operation is hypermedia links, which may link to related resources caused by the \nside-effects of the changes performed.\n\n### Instance Resources\n\nInstance resources can support the `GET`, `PUT`, `POST`, `PATCH` and `DELETE` operations.\n\n#### GET\n\nRetrieves the details of a specific resource by its identifier. The details retrieved can be controlled through \nproperty selection and property views. The content of the resource is returned within the body of the response in the \nacceptable media type. \n\n#### PUT\n\nAllows for and idempotent \"full update\" (complete replacement) on a specific resource. If the resource does not exist, \nit will be created; if it does exist, it is completely overwritten. Any omitted properties in the request are assumed to \nbe undefined/null. For \"partial updates\" use `POST` or `PATCH` instead. \n\nThe content of the `PUT` request is sent in the request body. The identifier of the resource is specified within the URL \n(not the request body). The response to a successful `PUT` request is a `201 CREATED` to represent the created status, \nwith a valid `Location` header field set to the URI that can be used to access to the newly created (or fully replaced) \nresource. \n\n#### POST\n\nPerforms a non-idempotent creation of a new resource. The `POST` of an instance resource most commonly occurs with the \nuse of nested resources (e.g. searching on a parent collection resource). The response to a `POST` of an instance \nresource is typically a `200 OK` if the resource is non-persistent, and a `201 CREATED` if there is a resource \ncreated/persisted as a result of the operation. This varies by endpoint.\n\n#### PATCH\n\nThe `PATCH` operation is used to perform a partial update of a resource. `PATCH` is a non-idempotent operation that\nenforces an atomic mutation of a resource. Only the properties specified in the request are to be overwritten on the \nresource it is applied to. If a property is missing, it is assumed to not have changed.\n\n#### DELETE\n\nPermanently removes the individual resource from the system. If the resource is an association between resources, only \nthe association is removed, not the resources themselves. A successful deletion of the resource should return \n`204 NO CONTENT` with no response body. This operation is not fully idempotent, as follow-up requests to delete a \nnon-existent resource should return a `404 NOT FOUND`.\n\n## Requests\n\nUnless otherwise indicated, the default request body media type is `application/json`.\n\n### Headers\n\nCommonly used request headers include:\n\n| Header | Example | Purpose | \n| ------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `Accept` | `application/json` | Defines what acceptable content types are allowed by the client. For all types, use `*/*`. |\n| `Accept-Encoding` | `deflate, gzip` | Allows for the encoding to be specified (such as gzip). |\n| `Accept-Language` | `en-US` | Indicates to the server the client's locale (defaults `en-US`). |\n| `Authorization ` | `Basic Base64(\"username:password\")` | Basic authentication |\n| `Token ` | `123456` | Two-factor authentication token (if enabled) |\n\n### Dates & Times\n\nDates and/or times are specified as strings in the ISO 8601 format(s). The following formats are supported as input:\n\n| Value | Format | Notes |\n| --------------------------- | ------------------------------------------------------ | ----------------------------------------------------- |\n| Date | YYYY-MM-DD | Defaults to 12 am UTC (if used for a date & time |\n| Date & time only | YYYY-MM-DD'T'hh:mm:ss[.nnn] | Defaults to UTC |\n| Date & time in UTC | YYYY-MM-DD'T'hh:mm:ss[.nnn]Z | |\n| Date & time w/ offset | YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm | |\n| Date & time w/ zone-offset | YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm[] | |\n \n### Timezones\n\nTimezones are specified in the regional zone format, such as `\"America/Los_Angeles\"`, `\"Asia/Tokyo\"`, or `\"GMT\"`.\n \n### Paging\n\nPagination is supported on certain collection resources using a combination of two query parameters, `page` and `size`. \nAs these are control parameters, they are prefixed with the underscore character. The page parameter dictates the \nzero-based index of the page to retrieve, and the `size` indicates the size of the page. \n\nFor example, `/resources?page=2&size=10` will return page 3, with 10 records per page, giving results 21-30.\n\nThe maximum page size for a request is 500.\n\n### Sorting\n\nSorting is supported on paginated resources with the `sort` query parameter(s). The sort query parameter(s) supports \nidentifying a single or multi-property sort with a single or multi-direction output. The format of the parameter is:\n\n```\nsort=property[,ASC|DESC]...\n```\n\nTherefore, the request `/resources?sort=name,title,DESC` would return the results sorted by the name and title \ndescending, in that order. The sort directions are either ascending `ASC` or descending `DESC`. With single-order \nsorting, all properties are sorted in the same direction. To sort the results with varying orders by property,\n multiple sort parameters are passed. \n \nFor example, the request `/resources?sort=name,ASC&sort=title,DESC` would sort by name ascending and title \ndescending, in that order.\n\n## Responses\n\nThe following response statuses may be returned by this API.\n \n| Status | Meaning | Usage |\n| ------ | ------------------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `200` | OK | The operation performed without error according to the specification of the request, and no more specific 2xx code is suitable. |\n| `201` | Created | A create request has been fulfilled and a resource has been created. The resource is available as the URI specified in the response, including the `Location` header. |\n| `202` | Accepted | An asynchronous task has been accepted, but not guaranteed, to be processed in the future. |\n| `400` | Bad Request | The request was invalid or cannot be otherwise served. The request is not likely to succeed in the future without modifications. |\n| `401` | Unauthorized | The user is unauthorized to perform the operation requested, or does not maintain permissions to perform the operation on the resource specified. |\n| `403` | Forbidden | The resource exists to which the user has access, but the operating requested is not permitted. |\n| `404` | Not Found | The resource specified could not be located, does not exist, or an unauthenticated client does not have permissions to a resource. |\n| `405` | Method Not Allowed | The operations may not be performed on the specific resource. Allowed operations are returned and may be performed on the resource. |\n| `408` | Request Timeout | The client has failed to complete a request in a timely manner and the request has been discarded. |\n| `413` | Request Entity Too Large | The request being provided is too large for the server to accept processing. |\n| `415` | Unsupported Media Type | The media type is not supported for the requested resource. |\n| `500` | Internal Server Error | An internal and unexpected error has occurred on the server at no fault of the client. |\n\n### Security\n\nThe response statuses 401, 403 and 404 need special consideration for security purposes. As necessary, \nerror statuses and messages may be obscured to strengthen security and prevent information exposure. The following is a \nguideline for privileged resource response statuses:\n\n| Use Case | Access | Resource | Permission | Status |\n| ------------------------------------------------------------------ | ------------------ |------------------- | ------------ | ------------ |\n| Unauthenticated access to an unauthenticated resource. | Unauthenticated | Unauthenticated | Yes | `20x` |\n| Unauthenticated access to an authenticated resource. | Unauthenticated | Authenticated | No | `401` |\n| Unauthenticated access to an authenticated resource. | Unauthenticated | Non-existent | No | `401` |\n| Authenticated access to a unauthenticated resource. | Authenticated | Unauthenticated | Yes | `20x` |\n| Authenticated access to an authenticated, unprivileged resource. | Authenticated | Authenticated | No | `404` |\n| Authenticated access to an authenticated, privileged resource. | Authenticated | Authenticated | Yes | `20x` |\n| Authenticated access to an authenticated, non-existent resource | Authenticated | Non-existent | Yes | `404` |\n\n### Headers\n\nCommonly used response headers include:\n\n| Header | Example | Purpose |\n| -------------------------- | --------------------------------- | --------------------------------------------------------------- |\n| `Allow` | `OPTIONS, GET` | Defines the allowable HTTP operations on a resource. |\n| `Cache-Control` | `no-store, must-revalidate` | Disables caching of resources (as they are all dynamic). |\n| `Content-Encoding` | `gzip` | The encoding of the response body (if any). |\n| `Location` | | Refers to the URI of the resource created by a request. |\n| `Transfer-Encoding` | `chunked` | Specified the encoding used to transform response. |\n| `Retry-After` | 5000 | Indicates the time to wait before retrying a request. |\n| `X-Content-Type-Options` | `nosniff` | Disables MIME type sniffing. |\n| `X-XSS-Protection` | `1; mode=block` | Enables XSS filter protection. |\n| `X-Frame-Options` | `SAMEORIGIN` | Prevents rendering in a frame from a different origin. |\n| `X-UA-Compatible` | `IE=edge,chrome=1` | Specifies the browser mode to render in. |\n\n### Format\n\nWhen `application/json` is returned in the response body it is always pretty-printed (indented, human readable output). \nAdditionally, gzip compression/encoding is supported on all responses. \n\n#### Dates & Times\n\nDates or times are returned as strings in the ISO 8601 'extended' format. When a date and time is returned (instant) the value is converted to UTC.\n\nFor example:\n\n| Value | Format | Example |\n| --------------- | ------------------------------ | --------------------- |\n| Date | `YYYY-MM-DD` | 2017-12-03 |\n| Date & Time | `YYYY-MM-DD'T'hh:mm:ss[.nnn]Z` | 2017-12-03T10:15:30Z |\n\n#### Content\n\nIn some resources a Content data type is used. This allows for multiple formats of representation to be returned\nwithin resource, specifically `\"html\"` and `\"text\"`. The `\"text\"` property returns a flattened representation suitable\nfor output in textual displays. The `\"html\"` property returns an HTML fragment suitable for display within an HTML \nelement. Note, the HTML returned is not a valid stand-alone HTML document.\n\n#### Paging\n\nThe response to a paginated request follows the format:\n\n```json\n{\n resources\": [ \n ... \n ],\n \"page\": { \n \"number\" : ...,\n \"size\" : ...,\n \"totalResources\" : ...,\n \"totalPages\" : ...\n },\n \"links\": [ \n \"first\" : {\n \"href\" : \"...\"\n },\n \"prev\" : {\n \"href\" : \"...\"\n },\n \"self\" : {\n \"href\" : \"...\"\n },\n \"next\" : {\n \"href\" : \"...\"\n },\n \"last\" : {\n \"href\" : \"...\"\n } \n ]\n}\n```\n\nThe `resources` property is an array of the resources being retrieved from the endpoint, each which should contain at \nminimum a \"self\" relation hypermedia link. The `page` property outlines the details of the current page and total\npossible pages. The object for the page includes the following properties:\n\n- number - The page number (zero-based) of the page returned.\n- size - The size of the pages, which is less than or equal to the maximum page size.\n- totalResources - The total amount of resources available across all pages.\n- totalPages - The total amount of pages.\n\nThe last property of the paged response is the `links` array, which contains all available hypermedia links. For \npaginated responses, the \"self\", \"next\", \"previous\", \"first\", and \"last\" links are returned. The \"self\" link must\nalways be returned and should contain a link to allow the client to replicate the original request against the \ncollection resource in an identical manner to that in which it was invoked. \n\nThe \"next\" and \"previous\" links are present if either or both there exists a previous or next page, respectively. \nThe \"next\" and \"previous\" links have hrefs that allow \"natural movement\" to the next page, that is all parameters \nrequired to move the next page are provided in the link. The \"first\" and \"last\" links provide references to the first\nand last pages respectively. \n\nRequests outside the boundaries of the pageable will result in a `404 NOT FOUND`. Paginated requests do not provide a \n\"stateful cursor\" to the client, nor does it need to provide a read consistent view. Records in adjacent pages may \nchange while pagination is being traversed, and the total number of pages and resources may change between requests \nwithin the same filtered/queries resource collection.\n\n#### Property Views\n\nThe \"depth\" of the response of a resource can be configured using a \"view\". All endpoints supports two views that can \ntune the extent of the information returned in the resource. The supported views are `summary` and `details` (the default). \nView are specified using a query parameter, in this format:\n\n```bash\n/?view={viewName}\n```\n\n#### Error\n\nAny error responses can provide a response body with a message to the client indicating more information (if applicable) \nto aid debugging of the error. All 40x and 50x responses will return an error response in the body. The format of the \nresponse is as follows:\n\n```json\n{\n \"status\": ,\n \"message\": ,\n \"links\" : [ {\n \"rel\" : \"...\",\n \"href\" : \"...\"\n } ]\n} \n ```\n \nThe `status` property is the same as the HTTP status returned in the response, to ease client parsing. The message \nproperty is a localized message in the request client's locale (if applicable) that articulates the nature of the \nerror. The last property is the `links` property. This may contain additional \n[hypermedia links](#section/Overview/Authentication) to troubleshoot.\n\n#### Search Criteria \n\nMultiple resources make use of search criteria to match assets. Search criteria is an array of search filters. Each \nsearch filter has a generic format of:\n\n```json\n{ \n \"field\": \"\", \n \"operator\": \"\", \n [\"value\": ,]\n [\"lower\": ,]\n [\"upper\": ]\n}\n \n```\n\nEvery filter defines two required properties `field` and `operator`. The field is the name of an asset property that\nis being filtered on. The operator is a type and property-specific operating performed on the filtered property. The\nvalid values for fields and operators are outlined in the table below. Depending on the data type of the operator\nthe value may be a numeric or string format.\n\nEvery filter also defines one or more values that are supplied to the operator. The valid values vary by operator\nand are outlined below.\n\n##### Fields\n\nThe following table outlines the search criteria fields and the available operators:\n\n| Field | Operators |\n| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `alternate-address-type` | `in` |\n| `container-image` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-like` `not-like` |\n| `container-status` | `is` `is-not` |\n| `containers` | `are` |\n| `criticality-tag` | `is` `is-not` `is-greater-than` `is-less-than` `is-applied` ` is-not-applied` |\n| `custom-tag` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-applied` `is-not-applied` |\n| `cve` | `is` `is-not` `contains` `does-not-contain` |\n| `cvss-access-complexity` | `is` `is-not` |\n| `cvss-authentication-required` | `is` `is-not` |\n| `cvss-access-vector` | `is` `is-not` |\n| `cvss-availability-impact` | `is` `is-not` |\n| `cvss-confidentiality-impact` | `is` `is-not` |\n| `cvss-integrity-impact` | `is` `is-not` |\n| `cvss-v3-confidentiality-impact` | `is` `is-not` |\n| `cvss-v3-integrity-impact` | `is` `is-not` |\n| `cvss-v3-availability-impact` | `is` `is-not` |\n| `cvss-v3-attack-vector` | `is` `is-not` |\n| `cvss-v3-attack-complexity` | `is` `is-not` |\n| `cvss-v3-user-interaction` | `is` `is-not` |\n| `cvss-v3-privileges-required` | `is` `is-not` |\n| `host-name` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-empty` `is-not-empty` `is-like` `not-like` |\n| `host-type` | `in` `not-in` |\n| `ip-address` | `is` `is-not` `in-range` `not-in-range` `is-like` `not-like` |\n| `ip-address-type` | `in` `not-in` |\n| `last-scan-date` | `is-on-or-before` `is-on-or-after` `is-between` `is-earlier-than` `is-within-the-last` |\n| `location-tag` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-applied` `is-not-applied` |\n| `mobile-device-last-sync-time` | `is-within-the-last` `is-earlier-than` |\n| `open-ports` | `is` `is-not` ` in-range` |\n| `operating-system` | `contains` ` does-not-contain` ` is-empty` ` is-not-empty` |\n| `owner-tag` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` `is-applied` `is-not-applied` |\n| `pci-compliance` | `is` |\n| `risk-score` | `is` `is-not` `is-greater-than` `is-less-than` `in-range` |\n| `service-name` | `contains` `does-not-contain` |\n| `site-id` | `in` `not-in` |\n| `software` | `contains` `does-not-contain` |\n| `vAsset-cluster` | `is` `is-not` `contains` `does-not-contain` `starts-with` |\n| `vAsset-datacenter` | `is` `is-not` |\n| `vAsset-host-name` | `is` `is-not` `contains` `does-not-contain` `starts-with` |\n| `vAsset-power-state` | `in` `not-in` |\n| `vAsset-resource-pool-path` | `contains` `does-not-contain` |\n| `vulnerability-assessed` | `is-on-or-before` `is-on-or-after` `is-between` `is-earlier-than` `is-within-the-last` |\n| `vulnerability-category` | `is` `is-not` `starts-with` `ends-with` `contains` `does-not-contain` |\n| `vulnerability-cvss-v3-score` | `is` `is-not` |\n| `vulnerability-cvss-score` | `is` `is-not` `in-range` `is-greater-than` `is-less-than` |\n| `vulnerability-exposures` | `includes` `does-not-include` |\n| `vulnerability-title` | `contains` `does-not-contain` `is` `is-not` `starts-with` `ends-with` |\n| `vulnerability-validated-status` | `are` |\n\n##### Enumerated Properties\n\nThe following fields have enumerated values:\n\n| Field | Acceptable Values |\n| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| `alternate-address-type` | 0=IPv4, 1=IPv6 |\n| `containers` | 0=present, 1=not present |\n| `container-status` | `created` `running` `paused` `restarting` `exited` `dead` `unknown` |\n| `cvss-access-complexity` |
  • L = Low
  • M = Medium
  • H = High
|\n| `cvss-integrity-impact` |
  • N = None
  • P = Partial
  • C = Complete
|\n| `cvss-confidentiality-impact` |
  • N = None
  • P = Partial
  • C = Complete
|\n| `cvss-availability-impact` |
  • N = None
  • P = Partial
  • C = Complete
|\n| `cvss-access-vector` |
  • L = Local
  • A = Adjacent
  • N = Network
|\n| `cvss-authentication-required` |
  • N = None
  • S = Single
  • M = Multiple
|\n| `cvss-v3-confidentiality-impact` |
  • L = Local
  • L = Low
  • N = None
  • H = High
|\n| `cvss-v3-integrity-impact` |
  • L = Local
  • L = Low
  • N = None
  • H = High
|\n| `cvss-v3-availability-impact` |
  • N = None
  • L = Low
  • H = High
|\n| `cvss-v3-attack-vector` |
  • N = Network
  • A = Adjacent
  • L = Local
  • P = Physical
|\n| `cvss-v3-attack-complexity` |
  • L = Low
  • H = High
|\n| `cvss-v3-user-interaction` |
  • N = None
  • R = Required
|\n| `cvss-v3-privileges-required` |
  • N = None
  • L = Low
  • H = High
|\n| `host-type` | 0=Unknown, 1=Guest, 2=Hypervisor, 3=Physical, 4=Mobile |\n| `ip-address-type` | 0=IPv4, 1=IPv6 |\n| `pci-compliance` | 0=fail, 1=pass |\n| `vulnerability-validated-status` | 0=present, 1=not present |\n\n##### Operator Properties \n\nThe following table outlines which properties are required for each operator and the appropriate data type(s):\n\n| Operator | `value` | `lower` | `upper` |\n| ----------------------|-----------------------|-----------------------|------------------------|\n| `are` | `string` | | |\n| `contains` | `string` | | |\n| `does-not-contain` | `string` | | |\n| `ends with` | `string` | | |\n| `in` | `Array[ string ]` | | |\n| `in-range` | | `numeric` | `numeric` |\n| `includes` | `Array[ string ]` | | |\n| `is` | `string` | | |\n| `is-applied` | | | |\n| `is-between` | | `string` (yyyy-MM-dd) | `numeric` (yyyy-MM-dd) |\n| `is-earlier-than` | `numeric` (days) | | |\n| `is-empty` | | | |\n| `is-greater-than` | `numeric` | | |\n| `is-on-or-after` | `string` (yyyy-MM-dd) | | |\n| `is-on-or-before` | `string` (yyyy-MM-dd) | | |\n| `is-not` | `string` | | |\n| `is-not-applied` | | | |\n| `is-not-empty` | | | |\n| `is-within-the-last` | `numeric` (days) | | |\n| `less-than` | `string` | | | \n| `like` | `string` | | |\n| `not-contains` | `string` | | |\n| `not-in` | `Array[ string ]` | | |\n| `not-in-range` | | `numeric` | `numeric` |\n| `not-like` | `string` | | |\n| `starts-with` | `string` | | |\n\n#### Discovery Connection Search Criteria \n\nDynamic sites make use of search criteria to match assets from a discovery connection. Search criteria is an array of search filters. \n\nEach search filter has a generic format of:\n\n```json\n{ \n \"field\": \"\", \n \"operator\": \"\", \n [\"value\": \"\",]\n [\"lower\": \"\",]\n [\"upper\": \"\"]\n}\n \n```\n\nEvery filter defines two required properties `field` and `operator`. The field is the name of an asset property that\nis being filtered on. The list of supported fields vary depending on the type of discovery connection configured \nfor the dynamic site (e.g vSphere, ActiveSync, etc.). The operator is a type and property-specific operating \nperformed on the filtered property. The valid values for fields outlined in the tables below and are grouped by the \ntype of connection. \n\nEvery filter also defines one or more values that are supplied to the operator. See \nSearch Criteria Operator Properties for more \ninformation on the valid values for each operator. \n\n##### Fields (ActiveSync)\n\nThis section documents search criteria information for ActiveSync discovery connections. The discovery connections \nmust be one of the following types: `\"activesync-ldap\"`, `\"activesync-office365\"`, or `\"activesync-powershell\"`. \n\nThe following table outlines the search criteria fields and the available operators for ActiveSync connections:\n\n| Field | Operators |\n| --------------------------------- | ------------------------------------------------------------- |\n| `last-sync-time` | `is-within-the-last` ` is-earlier-than` |\n| `operating-system` | `contains` ` does-not-contain` |\n| `user` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n\n##### Fields (AWS)\n\nThis section documents search criteria information for AWS discovery connections. The discovery connections must be the type `\"aws\"`. \n\nThe following table outlines the search criteria fields and the available operators for AWS connections:\n\n| Field | Operators |\n| ----------------------- | ------------------------------------------------------------- |\n| `availability-zone` | `contains` ` does-not-contain` |\n| `guest-os-family` | `contains` ` does-not-contain` |\n| `instance-id` | `contains` ` does-not-contain` |\n| `instance-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n| `instance-state` | `in` ` not-in` |\n| `instance-type` | `in` ` not-in` |\n| `ip-address` | `in-range` ` not-in-range` ` is` ` is-not` |\n| `region` | `in` ` not-in` |\n| `vpc-id` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n\n##### Fields (DHCP)\n\nThis section documents search criteria information for DHCP discovery connections. The discovery connections must be the type `\"dhcp\"`. \n\nThe following table outlines the search criteria fields and the available operators for DHCP connections:\n\n| Field | Operators |\n| --------------- | ------------------------------------------------------------- |\n| `host-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n| `ip-address` | `in-range` ` not-in-range` ` is` ` is-not` |\n| `mac-address` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n\n##### Fields (Sonar)\n\nThis section documents search criteria information for Sonar discovery connections. The discovery connections must be the type `\"sonar\"`. \n\nThe following table outlines the search criteria fields and the available operators for Sonar connections:\n\n| Field | Operators |\n| ------------------- | -------------------- |\n| `search-domain` | `contains` ` is` |\n| `ip-address` | `in-range` ` is` |\n| `sonar-scan-date` | `is-within-the-last` |\n\n##### Fields (vSphere)\n\nThis section documents search criteria information for vSphere discovery connections. The discovery connections must be the type `\"vsphere\"`. \n\nThe following table outlines the search criteria fields and the available operators for vSphere connections:\n\n| Field | Operators |\n| -------------------- | ------------------------------------------------------------------------------------------ |\n| `cluster` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n| `data-center` | `is` ` is-not` |\n| `discovered-time` | `is-on-or-before` ` is-on-or-after` ` is-between` ` is-earlier-than` ` is-within-the-last` |\n| `guest-os-family` | `contains` ` does-not-contain` |\n| `host-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n| `ip-address` | `in-range` ` not-in-range` ` is` ` is-not` |\n| `power-state` | `in` ` not-in` |\n| `resource-pool-path` | `contains` ` does-not-contain` |\n| `last-time-seen` | `is-on-or-before` ` is-on-or-after` ` is-between` ` is-earlier-than` ` is-within-the-last` |\n| `vm` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` |\n\n##### Enumerated Properties (vSphere)\n\nThe following fields have enumerated values:\n\n| Field | Acceptable Values |\n| ------------- | ------------------------------------ |\n| `power-state` | `poweredOn` `poweredOff` `suspended` |\n\n## HATEOAS\n\nThis API follows Hypermedia as the Engine of Application State (HATEOAS) principals and is therefore hypermedia friendly. \nHyperlinks are returned in the `links` property of any given resource and contain a fully-qualified hyperlink to\nthe corresponding resource. The format of the hypermedia link adheres to both the\n{json:api} v1 \n\"Link Object\" and \nJSON Hyper-Schema \n\"Link Description Object\"\nformats. For example:\n\n```json\n\"links\": [{\n \"rel\": \"\",\n \"href\": \"\"\n ...\n}]\n```\n\nWhere appropriate link objects may also contain additional properties than the `rel` and `href` properties, such as `id`, `type`, etc.\n\nSee the [Root](#tag/Root) resources for the entry points into API discovery.\n", "image": "", "baseURL": "https://:/", "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/rapid7.com/main/3", "version": "3", "tags": [ "rapid7.com", "main" ], "properties": [ { "type": "OpenAPI", "name": "OpenAPI definition", "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/rapid7.com/main/3/openapi.json", "mediaType": "application/openapi+json" }, { "type": "GitHubRepo", "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/rapid7.com/main/3" } ], "contact": [ { "FN": "Rapid7", "email": "support@rapid7.com" } ] } ] }