Bitsight

https://help.bitsighttech.com/hc/en-us
Admin
Bitsight is a cybersecurity rating and risk management platform offering solutions for security...
Tokens:459,315
Snippets:5,836
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example Request for Products in a Folder

Source: https://help.bitsighttech.com/hc/en-us/articles/360019516774-GET-Products-in-a-Folder

Uses cURL to perform a GET request to the products endpoint for a specific folder GUID.

```bash
curl https://api.bitsighttech.com/ratings/v1/folders/12349876-bbbb-5555-bbbb-example55555/products/ -u api_token:
```

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

### Example Request for Product Usage

Source: https://help.bitsighttech.com/hc/en-us/articles/360056038814-GET-Product-Usage-of-Companies-in-Your-Portfolio

A cURL command to retrieve companies using a specific product by its GUID.

```bash
curl https://api.bitsighttech.com/ratings/v1/portfolio/products/prod1234-prod-1234-prod-1234prod1234/companies -u api_token:
```

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

### Example Request for Service Provider Products

Source: https://help.bitsighttech.com/hc/en-us/articles/360010397933-GET-Service-Provider-Products-in-Your-Portfolio

Uses cURL to retrieve products for a specific provider identified by its GUID.

```bash
curl https://api.bitsighttech.com/ratings/v1/portfolio/providers/a5e23bf0-38d4-4cea-aa50-19ee75da481d/products -u api_token:
```

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

### Example Request for Service Provider Details

Source: https://help.bitsighttech.com/hc/en-us/articles/360037161033-GET-Service-Provider-Details

Use this cURL command to retrieve details for a specific provider by its GUID.

```bash
curl https://api.bitsighttech.com/ratings/v1/providers/a5e23bf0-38d4-4cea-aa50-19ee75da481d -u api_token:
```

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

### GET Product Usage Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360056106374-GET-Product-Usage-of-Companies-in-a-Ratings-Tree

Example JSON response containing the count and details of companies using the specified product.

```json
{
  "count":2,
  "results":[
    […]
    {
      "company_guid":"19d16bf5-11a6-467b-b7b1-f5563daece69",
      "company_name":"Pollinate, Inc.",
      "domain_count":2,
      "percent_dependent":15.4,
      "relationship_source":"bitsight"
    }
  ]
 }
```

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

### Example Request

Source: https://help.bitsighttech.com/hc/en-us/articles/360036664794-GET-Products-in-a-Specific-Folder

A cURL command to retrieve products for a specific folder and provider.

```bash
curl https://api.bitsighttech.com/ratings/v1/folders/fcc8b8c4-4fa3-4735-ac14-405ac7855d70/providers/a5e23bf0-38d4-4cea-aa50-19ee75da481d/products -u api_token:
```

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

### GET Product Types Request

Source: https://help.bitsighttech.com/hc/en-us/articles/360055871574-GET-Product-Types-in-a-Ratings-Tree

Example request using cURL to retrieve product types for a specific company GUID.

```bash
curl https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/company-tree/product-types -u api_token:
```

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

### Example Response for Products in a Folder

Source: https://help.bitsighttech.com/hc/en-us/articles/360019516774-GET-Products-in-a-Folder

A JSON response containing the count of products and an array of product details.

```json
{
  "count":123,
  "results":[
    […]
    {
      "product_guid":"55555555-pppp-rrrr-oooo-dddddddddddd",
      "product_name":"Black Hills POS",
      "product_types":[
        "Order Management"
      ],
      "provider_guid":"a5e23bf0-38d4-4cea-aa50-19ee75da481d",
      "provider_name":"Black Hills Technologies",
      "provider_industry":"Technology",
      "company_count":1,
      "domain_count":1,
      "percent_dependent":0.2,
      "percent_dependent_company":33.3,
      "relative_importance":0.015697703143963113,
      "relative_criticality":"medium"
    }
  ]
}
```

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

### GET Product Types Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360019694593-GET-Product-Types-in-a-Folder

Example JSON response containing the count of products and a list of product types with associated company GUIDs.

```json
{
  "count":1,
  "results":[
    {
      "product_type":"Audio / Video Delivery",
      "company_guids":[
        "feeccea4-e062-4cf5-9a3d-7034addb12d1",
        "3abbba22-62b7-492e-aeac-b1d67a2f45b3"
      ]
    }
  ]
}
```

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

### Example Response for Service Provider Products

Source: https://help.bitsighttech.com/hc/en-us/articles/360010397933-GET-Service-Provider-Products-in-Your-Portfolio

A sample JSON response containing product details such as product_guid, name, and criticality metrics.

```json
{
  [
    […]
    {
      "product_guid":"55555555-pppp-rrrr-oooo-dddddddddddd",
      "product_name":"Black Hills POS",
      "product_types":[
        "Order Management"
      ],
      "provider_guid":"a5e23bf0-38d4-4cea-aa50-19ee75da481d",
      "provider_name":"Black Hills Technologies",
      "provider_industry":"Technology",
      "company_count":1,
      "domain_count":1,
      "percent_dependent":0.0,
      "percent_dependent_company":0.0,
      "relative_importance":6.486631668032194E-6,
      "relative_criticality":"low"
    }
  ]
}
```

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

### GET /findings/{guid}

Source: https://help.bitsighttech.com/hc/en-us/articles/360022913734-GET-Finding-Details

Retrieves finding details for a specific company identified by its GUID.

```APIDOC
## GET /findings/{guid}

### Description
Retrieves a list of findings associated with a specific company.

### Method
GET

### Endpoint
/findings/{guid}

### Parameters
#### Path Parameters
- **guid** (String) - Required - The unique identifier of the company.

#### Query Parameters
- **details.infection.family** (String) - Optional - Filter by comma-separated infection names.
- **details.observed_ips_contains** (String) - Optional - Include findings from a particular IP address.
- **details.vulnerabilities.severity** (String) - Optional - Filter by vulnerability severity.
- **evidence_key** (String) - Optional - Filter by the company’s asset (domain or IP address).
- **expand** (String) - Optional - Include additional information (attributed_companies, remediation_history, assets.tag_details, tag_details).
- **first_seen** (String) - Optional - Include findings first seen on this date (YYYY-MM-DD).
- **first_seen_gt** (String) - Optional - Include findings first seen after this date (YYYY-MM-DD).
- **first_seen_gte** (String) - Optional - Include findings first seen on and after this date (YYYY-MM-DD).
- **first_seen_lt** (String) - Optional - Include findings first seen prior to this date (YYYY-MM-DD).
- **first_seen_lte** (String) - Optional - Include findings first seen on and prior to this date (YYYY-MM-DD).
- **last_remediation_status_date** (String) - Optional - Include findings with a remediation status change on this date (YYYY-MM-DD).
- **last_remediation_status_date_gt** (String) - Optional - Include findings with a remediation status change after this date (YYYY-MM-DD).
- **last_remediation_status_date_gte** (String) - Optional - Include findings with a remediation status change on and after this date (YYYY-MM-DD).
- **last_remediation_status_date_lt** (String) - Optional - Include findings with a remediation status change prior to this date (YYYY-MM-DD).
- **last_remediation_status_date_lte** (String) - Optional - Include findings with a remediation status change prior to and on this date (YYYY-MM-DD).
- **last_remediation_status_label** (String) - Optional - Filter by the current remediation status.
- **last_seen** (String) - Optional - Include findings last seen on this date (YYYY-MM-DD).
- **last_seen_gt** (String) - Optional - Include findings last seen after this date (YYYY-MM-DD).
- **last_seen_gte** (String) - Optional - Include findings last seen on and after this date (YYYY-MM-DD).
- **last_seen_lt** (String) - Optional - Include findings last seen prior to this date (YYYY-MM-DD).
- **last_seen_lte** (String) - Optional - Include findings last seen on and prior to this date (YYYY-MM-DD).
- **remediation_assignments** (String) - Optional - Filter by comma-separated user unique identifiers.
- **risk_vector_label** (String) - Optional - Filter by comma-separated risk vector slug names.
- **severity** (Decimal) - Optional - Filter by finding severity.
- **severity_gt** (Decimal) - Optional - Include findings with greater severity.
- **severity_gte** (Decimal) - Optional - Include findings with greater or equal severity.
- **severity_lt** (Decimal) - Optional - Include findings with lesser severity.
```

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

### GET /ratings/v1/companies/{guid}/threats/attestations/

Source: https://help.bitsighttech.com/hc/en-us/articles/35648010343447-GET-Company-Threat-Attestations

Retrieves a list of threat attestations for a given company identified by its GUID.

```APIDOC
## GET /ratings/v1/companies/{guid}/threats/attestations/

### Description
List all the company’s threat attestations.

### Method
GET

### Endpoint
https://api.bitsighttech.com/ratings/v1/companies/{guid}/threats/attestations/

### Parameters
#### Path Parameters
- **guid** (String) - Required - The company's unique identifier.

#### Query Parameters
- **limit** (Integer) - Optional - Default: 100
- **offset** (Integer) - Optional
- **sort** (String) - Optional
- **fields** (String) - Optional
- **threat.guid** (String) - Optional - Filter by threat unique identifier(s).
- **is_public** (Boolean) - Optional - Filter by public or private attestations.
- **is_latest** (Boolean) - Optional - Filter by the latest attestation per threat.
- **attestation.slug** (String) - Optional - Filter by attestation slug.
- **created_by.guid** (String) - Optional - Filter by the created by unique identifier(s).
- **created_time** (String) - Optional - Filter by created time equal to the value (ISO 8601).
- **created_time_lt** (String) - Optional - Filter by created time less than the value (ISO 8601).
- **created_time_lte** (String) - Optional - Filter by created time less than or equal to the value (ISO 8601).
- **created_time_gt** (String) - Optional - Filter by created time greater than the value (ISO 8601).
- **created_time_gte** (String) - Optional - Filter by created time greater than or equal to the value (ISO 8601).

### Response
#### Success Response (200)
- **links** (Object) - Pagination links.
- **count** (Integer) - Total number of results.
- **results** (Array) - List of threat attestation objects.

#### Response Example
{
  "links": {
    "next": null,
    "previous": null
  },
  "count": 1,
  "results": [
    {
      "threat": {
        "guid": "11111111-aaaa-1111-aaaa-111111111111",
        "name": "CVE-2025-XXXX"
      },
      "attestation": {
        "slug": "UNDER_REVIEW",
        "name": "Under Review"
      },
      "is_public": false,
      "is_latest": true,
      "created_time": "2025-08-03T11:46:59.964838Z",
      "created_by": {
        "guid": "1a1a1a1a-a1a1-1a1a-a1a1-1a1a1a1a1a1a",
        "name": "User Name"
      }
    }
  ]
}
```

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

### Example Request for Creating a User

Source: https://help.bitsighttech.com/hc/en-us/articles/360048214814-POST-Create-a-New-User

A cURL command demonstrating how to send a POST request to create a new user with basic required fields.

```bash
curl -X POST --data-ascii '{"friendly_name": "Arnold","formal_name": "Arnold Brown","email": "arnold@actorsfilms.us"}' https://api.bitsighttech.com/ratings/v2/users -u api_token: --header "Content-Type:application/json"
```

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

### GET: Tiered Company GUID by Action Plan

Source: https://help.bitsighttech.com/hc/en-us/sections/360003866093-Tiers-API-Endpoint

Retrieves the GUID of a tiered company based on an action plan.

```APIDOC
## GET /tiers/company-guid

### Description
Retrieves the GUID of a tiered company associated with a specific action plan.
```

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

### GET Tiered Company GUIDs Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360047910773-GET-Tiered-Company-GUID-by-Action-Plan

The response returns an object containing arrays of GUIDs for each action plan category.

```json
{
  "escalate":[
    "aaaaaaaa-1111-aaaa-1111-aaa111aaa111",
    "bbbbbbbb-2222-bbbb-2222-bbb222aaabbb"
  ],
  "review":[
    "aaa111aa-aa11-11aa-11aa-aaa111111aaa"
  ],
  "monitor":[
    "2b2b2b2b-2b2b-2b2b-2b2b-2b2b2b2b2b2b",
    "1a1a1a1a-a1a1-a1a1-1a1a-1a1a1a1a1a1a"
  ]
}
```

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

### GET Tiered Company GUIDs Request

Source: https://help.bitsighttech.com/hc/en-us/articles/360047910773-GET-Tiered-Company-GUID-by-Action-Plan

Use this cURL command to retrieve the list of company GUIDs organized by action plan.

```bash
curl 'https://api.bitsighttech.com/ratings/v1/tiers/vendor-action-plan' -u api_token:
```

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

### KPI Module Configuration Example

Source: https://help.bitsighttech.com/hc/en-us/articles/115015829747-Infection-Detection-API-Guide

Example URL parameter configuration for the KPI module to aggregate by type and country code.

```text
...&otherfilters&modules=kpi&kpi=type,_geo_ip.country_code
```

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

### Example Response

Source: https://help.bitsighttech.com/hc/en-us/articles/23503330664343-GET-Web-Application-Security-Evidence-Components-with-Known-Vulnerabilities

A sample JSON response structure showing library details and associated CVEs.

```json
{
  "library":"jquery-ui",
  "version":"1.12.1",
  "cves":[
    {
      "cveId":"CVE-2021-41182"
    },
    […]
  ],
  ⊕ See additional evidences
}
```

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

### GET /ratings/v1/companies/{guid}/findings/{rolledup_observation_id}/comments

Source: https://help.bitsighttech.com/hc/en-us/articles/31234993032087-GET-Finding-Comments

Retrieves a list of comments for a specific finding identified by the company GUID and the rolled up observation ID.

```APIDOC
## GET /ratings/v1/companies/{guid}/findings/{rolledup_observation_id}/comments

### Description
View finding comments, which can be used to track remediation changes.

### Method
GET

### Endpoint
https://api.bitsighttech.com/ratings/v1/companies/{guid}/findings/{rolledup_observation_id}/comments

### Parameters
#### Path Parameters
- **guid** (string) - Required - Identify the company to query.
- **rolledup_observation_id** (string) - Required - Identify the finding to query.

#### Query Parameters
- **expand** (string) - Optional - Include additional information. Values: `remediation` = Remediation information.

### Request Example
curl https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/findings/SzL4Z5sQ3aWHdqx_EhEllQ==/comments -u api_token:

### Response
#### Success Response (200)
- **links** (object) - Pagination links.
- **count** (integer) - Number of comments returned.
- **results** (array) - List of comment objects.

#### Response Example
{
  "links": {
    "next": null,
    "previous": null
  },
  "count": 1,
  "results": [
    {
      "guid": "1efc88fd-29b4-4869-8c89-ccc362f8f630",
      "thread_guid": "681b53fb-edbf-4f31-9726-8fe14ed8a12e",
      "created_time": "2025-03-18T15:50:52.241772Z",
      "last_update_time": "2025-03-18T15:50:52.241798Z",
      "message": "example comment",
      "is_public": false,
      "is_deleted": false,
      "parent_guid": null,
      "author": {
        "guid": "bd003dbc-1234-4b83-a4d8-4c417120a79c",
        "name": "User Name"
      },
      "company": {
        "guid": "a940bb61-33c4-42c9-9231-c8194c305db3",
        "name": "Company Name"
      },
      "tagged_users": [],
      "remediation": {
        "current": {
          "status": "Work In Progress",
          "assignments": [
            {
              "guid": "bd003dbc-1234-4b83-a4d8-4c417120a79c",
              "name": "User Name"
            }
          ]
        },
        "previous": {
          "status": "Open",
          "assignments": []
        }
      }
    }
  ]
}
```

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

### GET /v1/folders/{folder_guid}

Source: https://help.bitsighttech.com/hc/en-us/articles/232230788-Folders-API-Endpoint

Returns details of a single folder by its GUID.

```APIDOC
## GET /v1/folders/{folder_guid}

### Description
Returns details of a single folder.

### Method
GET

### Endpoint
/v1/folders/{folder_guid}

### Parameters
#### Path Parameters
- **folder_guid** (string) - Required - The unique identifier of the folder.
```

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

### Example Request

Source: https://help.bitsighttech.com/hc/en-us/articles/360056108194-GET-Domains-of-a-Company-Using-a-Specific-Product

A cURL command to retrieve domains for a specific company and product.

```bash
curl https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/products/prod1234-prod-1234-prod-1234prod1234/domains -u api_token:
```

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

### Example Request

Source: https://help.bitsighttech.com/hc/en-us/articles/14278982050711-GET-Compare-Client-to-the-Underwriting-Guidelines

A cURL command to retrieve the underwriting guideline comparison for a specific client.

```bash
curl https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/underwriting-guidelines -u api_token:
```

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

### GET Tiers Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360021083694-GET-Tiers

Example JSON response structure returned by the API.

```json
[
  {
    "rank":1,
    "guid":"e325bd1d-b5ee-4fa5-a1ee-8e87518b0746",
    "name":"Tier 1",
    "description":"PCI or Network access",
    "companies":[
      "221c9760-60a9-4434-9805-aca970aae50a",
      "de4e1348-10d3-4c59-8c16-9817a86926ae",
      "d8fa2aae-6b5c-4b92-8793-0ab08d85dcb8"
    ],
    "email_enabled":false,
    "content_subscription_types":[
      "continuous_monitoring",
      "alerts-only"
    ]
  },
  […]
]
```

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

### GET Findings Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360022913734-GET-Finding-Details

Example JSON response structure returned by the findings endpoint.

```json
{
  "links":{
    "previous":null,
    "next":null
  },
  "count":1,
  "results":[
    {
      "temporary_id":"A9Jq47BBjea129322347d12e29c54b488752b3b71e",
      "affects_rating":false,
      "assets":[
        {
          "asset":"11.111.111.111",
          "identifier":null,
          "category":"high",
          "importance":0.09,
          "is_ip":true,
          "asset_type":"IP",
          "is_monitored":false
        }
      ],
      "details":{
        "cvss": {
          "base": [
            10.0
          ]
        },
        "check_pass":"",

        ⊕ Details Vary by Risk Vector

        "evidence_key":"11.111.111.111:23",
        "first_seen":"2019-05-29",
        "last_seen":"2019-12-20",
        "related_findings":[ ],
        "risk_category":"Diligence",
        "risk_vector":"open_ports",
        "risk_vector_label":"Open Ports",
        "rolledup_observation_id":"_aAAa1AA_a1aAA1A1aaAAa==",
        "severity":10.0,
        "severity_category":"severe",
        "tags":[
          "Remote Office"
        ],
        "tag_details":[
          {
            "guid":"4f99d64c-c3d8-4e08-b346-14f042e97116",
            "name":"Corporate Infra",
            "is_inherited":false,
            "is_public":false
          }
        ],
        "remediation_history":{
          "last_requested_refresh_date":"2024-06-19",
            "last_refresh_status_date":"2024-06-23",
            "last_refresh_status_label":"failed",
          "last_refresh_status_reason": "asset_not_found",
            "last_refresh_reason_code":"asset unreachable",
            "last_refresh_requester": "1e10564d-fawa-4331-0000-6f7588b55a98",
          "result_finding_date": null
        },
        "asset_overrides":[
          {
            "asset":"11.111.111.111",
            "importance":"high",
            "override_importance":null
          }
        ],
        "duration":"7 days",
        "comments":"User from Actors Films said: \"Look at this finding\" at 2018-11-29 20:30 UTC;\nArnold Brown said: \"I changed the remediation status.\" at 2020-08-18 18:38 UTC",
        "remaining_decay":90,
        "remediated":false,
        "impacts_risk_vector_details":"AFFECTS_RATING"
        "attributed_companies":[
          {
            "guid":"44444444-cccc-4444-cccc-444444444444",
            "name":"Actors Film Studio"
          }
        ]
      },
    }
  ]
}
```

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

### Example Response for User Creation

Source: https://help.bitsighttech.com/hc/en-us/articles/360048214814-POST-Create-a-New-User

The JSON response returned upon successfully creating a new user, including the assigned GUID and default settings.

```json
{
  "guid":"11111111-aaaa-1111-aaaa-111111111111",
  "friendly_name":"Arnold",
  "formal_name":"Arnold Brown",
  "email":"arnold@actorsfilms.us",
  "group":{
    "guid":"bbbbbbbb-2222-bbbb-2222-bbbbbbbbbbbb",
    "name":"All Companies"
  },
  "status":"Created",
  "last_login_time":null,
  "joined_time":"2020-02-02T20:20:20Z",
  "roles":[
    {
      "name":"User",
      "slug":"customer_user"
    }
  ],
  "is_available_for_contact":false,
  "is_company_api_token":false,
  "features":[
    {
      "slug":"wfh-ro",
      "value":false,
      "can_update":true
    }
  ]
}
```

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

### Example Request for Product Usage

Source: https://help.bitsighttech.com/hc/en-us/articles/360057946193-GET-Product-Usage-of-Companies-in-a-Folder

Uses cURL to retrieve product usage data for companies in a specific folder.

```bash
curl https://api.bitsighttech.com/ratings/v1/folders/4ce9df6d-e92b-4a5c-9530-521dae4a5f83/products/prod1234-prod-1234-prod-1234prod1234/companies -u api_token:
```

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

### GET Findings Request

Source: https://help.bitsighttech.com/hc/en-us/articles/360022913734-GET-Finding-Details

Example cURL command to retrieve findings for a specific company.

```bash
curl https://api.bitsighttech.com/ratings/v1/companies/A9Jq47BBjea129322347d12e29c54b488752b3b71e/findings -u api_token:
```

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

### GET Users Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360025814073-GET-Users-v1

Example JSON response containing a list of user objects.

```json
[
  {
    "friendly_name":"Jane",
    "formal_name":"Jane Smith",
    "first_name":"Jane",
    "last_name":"Smith",
    "email":"jane.smith@domain.com",
    "guid":"630867c3-c95c-4408-a07a-ed576cda8ede"
  }
]
```

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

### Example Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360019753714-PATCH-Manage-Shared-Folder-Permissions

The server returns the updated folder details upon a successful request.

```json
{
  "shared_options":{
    "is_shared":true,
    "shared_with_all_users":false,
    "group_can_edit_contents":false,
    "group_can_edit_properties":false,
    "shared_with_users":[
      {
        "email":"user@example.com",
        "can_edit_folder_contents":false,
        "can_edit_folder_properties":false
      }
    ]
  }
}
```

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

### GET Users Request

Source: https://help.bitsighttech.com/hc/en-us/articles/360025814073-GET-Users-v1

Example request using cURL to retrieve the list of users.

```bash
curl 'https://api.bitsighttech.com/ratings/v1/users' -u api_token:
```

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

### Desktop Software Finding Details Response

Source: https://help.bitsighttech.com/hc/en-us/articles/17834623862039-GET-Desktop-Software-Finding-Details

Example JSON response containing finding details, including operating system and user agent information.

```json
{
  "links":{
    "next":"https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/findings?limit=100&offset=100&risk_vector=desktop_software",
    "previous":null
  },
  "count":266,
  "results":[
    {
      "temporary_id":"A9Jq47BBje16e6e8d144bd8121cb4b4b2c941579f5",
      "affects_rating":true,
      "assets":[
        {
          "asset":"24.6.16.69",
          "identifier":null,
          "category":"low",
          "importance":0.0,
          "is_ip":true
        }
      ],
      "details":{
        "cvss":{
          "base":[ ]
        },
        "check_pass":"",
        "estimation_of_users":"1",
        "diligence_annotations":{
          "count_ips":1,
          "operating_system_rule":{
            "version":"10.15.7",
            "eol":"9999-01-01",
            "launch":"2020-09-24",
            "is":"match"
          },
          "user_agent_rule":{
            "version":"113",
            "eol":"2023-06-06",
            "launch":"2023-05-02",
            "is":"match"
          },
          "sample_ips":[
            "24.6.16.69"
          ],
          "sample_user_agent_strings":[
            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36"
          ],
          "sample_domains":[
            "avgle.com"
          ]
          "sample_records": [
            {
              "ip": "63.208.139.45",
              "timestamp": "timestamp",
              "user_agent": "Mozilla/5.0 (X11; CrOS x86_64 14541.0.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
              "domain": "www.dictionary.com"
            }
          ]
        },
        "geo_ip_location":"US",
        "country":"United States",
        "grade":"GOOD",
        "operating_system_family":"Mac OS X",
        "operating_system_grade":"GOOD",
        "operating_system_name":"macOS",
        "operating_system_support_status":"SUPPORTED",
        "operating_system_version":"10.15.7",
        "remediations":[
          {
            "message":"Supported Operating System and Browser",
            "help_text":"The operating system and browser are both supported.",
            "remediation_tip":""
          }
        ],
        "sample_timestamp":"2023-06-09T23:59:59Z",
        "user_agent_family":"Chrome",
        "user_agent_grade":"GOOD",
        "user_agent_support_status":"SUPPORTED",
        "user_agent_version":"113",
        "vulnerabilities":[ ],
        "rollup_end_date":"2023-06-09",
        "rollup_start_date":"2023-05-19",
        "searchable_details":"Supported Operating System and Browser"
      },
      "evidence_key":"Mac OS X 10.15.7 / Chrome 113.0.0",
      "first_seen":"2023-05-19",
      "last_seen":"2023-06-09",
      "related_findings":[ ],
      "risk_category":"Diligence",
      "risk_vector":"desktop_software",
      "risk_vector_label":"Desktop Software",
      "rolledup_observation_id":"kkMa1MuYiptCdylSJzGDoA==",
      "severity":1.0,
      "severity_category":"minor",
      "tags":[
        "Widget Division"
      ],
      "remediation_history":{
        "last_requested_refresh_date":"2024-06-19",
          "last_refresh_status_date":"2024-06-23",
          "last_refresh_status_label":"failed",
        "last_refresh_status_reason": "asset_not_found",
          "last_refresh_reason_code":"asset unreachable",
          "last_refresh_requester": "1e10564d-fawa-4331-0000-6f7588b55a98",
        "result_finding_date": null
      },
      "asset_overrides":[ ],
      "duration":null,
      "comments":null,
      "remaining_decay":62,
      "remediated":null
    },
    […]
  ]
}
```

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

### GET /ratings/v1/companies/{company_guid}/observations

Source: https://help.bitsighttech.com/hc/en-us/articles/360016546433-GET-Detailed-Company-Observations

Retrieve detailed observations for a company identified by its GUID.

```APIDOC
## GET /ratings/v1/companies/{company_guid}/observations

### Description
Retrieve detailed information (observations) about the risk category data of companies in your portfolio. This endpoint shows individual events that comprise the ones shown in the platform.

### Method
GET

### Endpoint
/ratings/v1/companies/{company_guid}/observations

### Parameters
#### Path Parameters
- **company_guid** (String) - Required - Identify the company to query.

#### Query Parameters
- **domain_name** (String) - Optional - Filter by domain name.
- **end_date** (String) - Optional - Filter by the observation’s end date (YYYY-MM-DD).
- **grades** (String) - Optional - Filter by comma-separated finding grades.
- **ip_address** (String) - Optional - Filter by IP address (IPv4 or IPv6).
- **limit** (Integer) - Optional - Set the maximum number of results (1-1000). Default: 100.
- **port** (Integer) - Optional - Filter observations on a particular network port (up to 65535).
- **risk_types** (String) - Optional - Filter by comma-separated observation risk types.
- **start_date** (String) - Optional - Filter by the observation’s starting date (YYYY-MM-DD).
```

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

### GET /ratings/v1/companies/{company_guid}

Source: https://help.bitsighttech.com/hc/en-us/articles/360015690713-GET-Company-Details

Retrieves detailed information for a specific company identified by its GUID.

```APIDOC
## GET /ratings/v1/companies/{company_guid}

### Description
Get a company’s details, including their rating, rating history, risk vector grades, company information, and relationship details.

### Method
GET

### Endpoint
https://api.bitsighttech.com/ratings/v1/companies/{company_guid}

### Parameters
#### Path Parameters
- **company_guid** (String) - Required - The unique identifier for the company.

#### Query Parameters
- **format** (String) - Optional - The response format (Value: json).
- **fields** (Array) - Optional - Comma-separated field names to filter the response (e.g., industry_average, industry_percentile).

### Request Example
curl https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3 -u api_token:

### Response
#### Success Response (200)
- **guid** (String) - Company unique identifier.
- **name** (String) - Company name.
- **rating_details** (Object) - Detailed rating information.
- **ratings** (Array) - Historical rating data.
- **industry** (String) - Industry sector.

#### Response Example
{
  "guid": "a940bb61-33c4-42c9-9231-c8194c305db3",
  "name": "Saperix, Inc.",
  "industry": "Technology",
  "rating_details": {},
  "ratings": []
}
```

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

### Example API Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360036928614-GET-Products-of-a-Specific-Service-Provider-in-a-Ratings-Tree

A sample JSON response containing product details such as product GUID, name, types, and provider information.

```json
{
  [
    […]
    {
      "product_guid":"55555555-pppp-rrrr-oooo-dddddddddddd",
      "product_name":"Black Hills POS",
      "product_types":[
        "Order Management"
      ],
      "provider_guid":"a5e23bf0-38d4-4cea-aa50-19ee75da481d",
      "provider_name":"Black Hills Technologies",
      "provider_industry":"Technology",
      "company_count":1,
      "domain_count":1,
      "percent_dependent":6.3,
      "percent_dependent_company":9.1,
      "relative_importance":0.09375,
      "relative_criticality":"high"
    }
  ]
}
```

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

### GET Findings in a Folder Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360051249573-GET-Findings-in-a-Folder

Example JSON response containing the findings summary statistics.

```json
[
  {
    "start_date":"2020-05-01",
    "end_date":"2020-06-30",
    "stats":[
      {
        "id":"CVE-2012-2532",
        "name":"CVE-2012-2532",
        "count":1,
        "severity":null,
        "severity_category":null,
        "confidence":"LOW"
      }
    ]
  }
]
```

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

### Example Response

Source: https://help.bitsighttech.com/hc/en-us/articles/360056108194-GET-Domains-of-a-Company-Using-a-Specific-Product

A JSON response containing the count of domains and detailed product usage information.

```json
{
  "count":2,
  "results":[
    […]
    {
      "importance":0.0,
      "criticality":"low",
      "domain_name":"kennedymotors.com",
      "product_count":13
    }
  ]
}
```

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

### GET /ratings/v1/folders/{folder_guid}/findings/summary

Source: https://help.bitsighttech.com/hc/en-us/articles/360051249573-GET-Findings-in-a-Folder

Retrieves a summary of findings for a specific folder identified by its GUID.

```APIDOC
## GET /ratings/v1/folders/{folder_guid}/findings/summary

### Description
See the presence of findings in a folder.

### Method
GET

### Endpoint
https://api.bitsighttech.com/ratings/v1/folders/{folder_guid}/findings/summary

### Parameters
#### Path Parameters
- **folder_guid** (String) - Required - Identify the folder to query.

#### Query Parameters
- **type** (String) - Optional - Filter by risk type (slug name).
- **confidence** (String) - Optional - Risk confidence level (LOW, HIGH).

### Request Example
curl https://api.bitsighttech.com/ratings/v1/folders/folder_guid/findings/summary -u api_token:

### Response
#### Success Response (200)
- **start_date** (String) - The beginning date of this summary.
- **end_date** (String) - The ending date of this summary.
- **stats** (Array) - Folder statistics.
  - **id** (String) - The CVE ID of prominent vulnerabilities.
  - **name** (String) - The CVE ID or vulnerability name.
  - **count** (Integer) - This value is always 1 for folder statistics.
  - **severity** (Null) - For internal Bitsight use.
  - **severity_category** (Null) - For internal Bitsight use.
  - **confidence** (String) - Risk confidence level (LOW, HIGH).

#### Response Example
[
  {
    "start_date": "2020-05-01",
    "end_date": "2020-06-30",
    "stats": [
      {
        "id": "CVE-2012-2532",
        "name": "CVE-2012-2532",
        "count": 1,
        "severity": null,
        "severity_category": null,
        "confidence": "LOW"
      }
    ]
  }
]
```

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

### Role and Feature Examples

Source: https://help.bitsighttech.com/hc/en-us/articles/360048216934-PATCH-Edit-a-User

Examples of the JSON structure for updating user roles and feature flags.

```json
[{"slug": "customer_user"}]
```

```json
[{"slug": "wfh-ro", "value": true}]
```

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

### GET /domain-squatting/{company_guid}/

Source: https://help.bitsighttech.com/hc/en-us/articles/360051017334-GET-Domain-Squatting-Details

Retrieves domain squatting activity for an organization identified by its company GUID.

```APIDOC
## GET /domain-squatting/{company_guid}/

### Description
See Domain Squatting activity on an organization’s domains.

### Method
GET

### Endpoint
https://api.bitsighttech.com/domain-squatting/{company_guid}/

### Parameters
#### Path Parameters
- **company_guid** (String) - Required - Identify the company to query.

### Request Example
curl https://api.bitsighttech.com/domain-squatting/1263b9c6-af38-4497-84ee-e15efdb065e9/ -u api_token:

### Response
#### Success Response (200)
- **domain** (String) - A domain (asset) that's authentically owned by the organization.
- **permutations** (Array) - Variations of the domain.
- **name** (String) - A variation of the domain name.
- **state** (String) - The current state of the variation (Registered to company, Unregistered).
- **type** (String) - The category of domain squatting.
- **timestamp** (String) - The date and time when this data set was last updated (YYYY-MM-DD HH:MM:SS).

#### Response Example
[
  {
    "domain": "goliathinvest.com",
    "permutations": [
      {
        "name": "goliathinvest.com",
        "state": "Registered to company",
        "type": "Original*"
      }
    ],
    "timestamp": "2020-07-08 12:48:19.297428"
  }
]
```

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

### Asset Response Example

Source: https://help.bitsighttech.com/hc/en-us/articles/36154905163799-GET-Assets

Example JSON structure showing wildcard and monitoring status within an asset object.

```json
{
 "is_monitored":false,  
 "is_wildcard": true,  
 "wildcard": {  
   "domain_root": "*.example.com",  
   "relationship": {  
          "slug": "WILDCARD_ROOT",  
          "Name": "Wildcard Root",  
   }  
 },  
 "cloud_context": { ... }  
}
```

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

### GET /ratings/v1/companies/{guid}/threats/attestations/summaries

Source: https://help.bitsighttech.com/hc/en-us/articles/35648258122135-GET-Company-Threat-Attestations-Summaries

Retrieves summarized threat attestations data for a specified company.

```APIDOC
## GET /ratings/v1/companies/{guid}/threats/attestations/summaries

### Description
Retrieves summarized threat attestations data for a company.

### Method
GET

### Endpoint
/ratings/v1/companies/{guid}/threats/attestations/summaries

### Parameters
#### Path Parameters
- **guid** (String) - Required - The company's unique identifier.

#### Query Parameters
- **threat.guid** (String) - Optional - Filter by threat unique identifier(s) (comma-separated).
- **is_public** (Boolean) - Optional - Determines whether public (true) or private (false) attestations are displayed.
- **is_latest** (Boolean) - Optional - When true, only the most recent attestations per threat are displayed.
- **attestation.slug** (String) - Optional - Filter by attestation slug (comma-separated list: UNREVIEWED, UNDER_REVIEW, NOT_VULNERABLE, RISK_ACCEPTED).
- **created_by.guid** (String) - Optional - Filter by the created by unique identifier(s) (comma-separated).
- **created_time** (String) - Optional - Filter by created time equal to the value (ISO 8601).
- **created_time_lt** (String) - Optional - Filter by created time less than the value (ISO 8601).
- **created_time_lte** (String) - Optional - Filter by created time less than or equal to the value (ISO 8601).
- **created_time_gt** (String) - Optional - Filter by created time greater than the value (ISO 8601).
- **created_time_gte** (String) - Optional - Filter by created time greater than or equal to the value (ISO 8601).

### Response
#### Success Response (200)
- **attestations** (Array) - List of summarized attestations.

#### Response Example
{
  "attestations": [
    {
      "slug": "UNREVIEWED",
      "threat_guids": [
        "11111111-bbbb-1111-bbbb-111111111111"
      ]
    },
    {
      "slug": "UNDER_REVIEW",
      "threat_guids": [
        "11111111-aaaa-1111-aaaa-111111111111"
      ]
    }
  ]
}
```

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

### Example API response

Source: https://help.bitsighttech.com/hc/en-us/articles/360057768813-GET-Products-in-a-Ratings-Tree

The response returns a count of products and an array of product details including provider information and criticality metrics.

```json
{
  "count":25,
  "results":[
    […]
    {
      "product_guid":"55555555-pppp-rrrr-oooo-dddddddddddd",
      "product_name":"Black Hills POS",
      "product_types":[
        "Order Management"
      ],
      "provider_guid":"a5e23bf0-38d4-4cea-aa50-19ee75da481d",
      "provider_name":"Black Hills Technologies",
      "provider_industry":"Technology",
      "company_count":1,
      "domain_count":2,
      "percent_dependent":8.3,
      "percent_dependent_company":9.1,
      "relative_importance":0.10714285714285714,
      "relative_criticality":"high"
    }
  ]
}
```

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

### Example Response for Threat Attestations Summaries

Source: https://help.bitsighttech.com/hc/en-us/articles/35648448575767-GET-Threat-Attestations-Summaries

Displays the JSON structure returned by the threat attestations summaries endpoint, containing a list of attestations with their respective slugs, threat GUIDs, and company GUIDs.

```json
{
"attestations": [
{
"slug": "UNREVIEWED",
"threat_guids": [
"11111111-bbbb-1111-bbbb-111111111111"
],
"company_guids": [
"feeccea4-e062-4cf5-9a3d-7034addb12d1"
]
},
{
"slug": "UNDER_REVIEW",
"threat_guids": [
"11111111-aaaa-1111-aaaa-111111111111"
],
"company_guids": [
"d3c1564e-9248-4fc4-9344-887f4bb140d3"
]
}
]
}
```

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

### GET Findings in a Folder Request

Source: https://help.bitsighttech.com/hc/en-us/articles/360051249573-GET-Findings-in-a-Folder

Example cURL request to retrieve findings summary for a specified folder.

```bash
curl https://api.bitsighttech.com/ratings/v1/folders/folder_guid/findings/summary -u api_token:
```
Tokens:
Raw