Security Performance Management
Continuous Monitoring
Cyber Insurance
National Cybersecurity

Articles in this section

API Documentation Overview

Avatar
Ingrid
Follow
  • September 25, 2020: Endpoint support & deprecation.

The Bitsight API allows developers to build applications around the Bitsight data or integrate Bitsight Security Ratings into their existing systems, such as Archer. Developers can access the current security rating for each company in their portfolio, each industry, and daily ratings for each company and weekly ratings for each industry.

Integrate with Bitsight

The Bitsight API is organized on Representational_state_transfer (REST). It can be explored using either cURL or a web browser. Built-in HTTP features that can be understood by all standard HTTP clients are used, such as basic access authentication.

JSON will be returned by default for all responses from the API, including errors. XML responses are available when specified as part of the request (see the XML request example for details).

URL

https://api.bitsighttech.com/ratings/v…

See the available endpoints.

Example Request

curl https://api.bitsighttech.com/ratings/v… -u api_token:

cURL uses the -u flag to pass basic authentication credentials. Adding a colon after your API token will prevent it from asking you for a password. JSON is returned by default.

JSON responses are the same for Accept and X-Bitsight-Accept headers (see the Accept header example).

Example Response

{
"version": 1,
  "name": "Bitsight API",
  "resources": [
    {
      "href": "https://api.bitsighttech.com/ratings/v1/companies",
      "name": "Companies"
    },
    {
      "href": "https://api.bitsighttech.com/ratings/v1/industries",
      "name": "Industries"
    },
    {
      "href": "https://api.bitsighttech.com/ratings/v1/alerts",
      "name": "Alerts"
    },
      "href": "https://api.bitsighttech.com/ratings/v1/subscriptions",
      "name": "Subscriptions"
    }
  ],
  "disclaimer": "This API contains sensitive information intended only for authorized viewers. All content is the property of Bitsight and cannot be shared, copied, or distributed without the express permission of Bitsight. Use of this data must adhere to the Bitsight Terms of Service."
}

How to Get Responses in XML

Your systems may require XML input to integrate Bitsight data. In this case, use the “Accept” header to request an XML response. The Accept header within your request needs to be set to “application/xml,” in order to receive an XML response.

Example Request

curl https://api.bitsighttech.com/ratings/v… -u api_token: -H "Accept: application/xml"

Example XML Request with an alternate Accept header:

curl https://api.bitsighttech.com/ratings/v… -u api_token: -H "X-Bitsight-Accept: application/xml"

This is case-sensitive. When troubleshooting, ensure the capitalization of X-Bitsight-Accept is correct.

Example Response

XML responses are the same for Accept and X-Bitsight-Accept:

<?xml version="1.0" encoding="utf-8"?>
<root>
    <version>1</version>
    <name>Bitsight API</name>
    <resources>
        <list-item>
        <href>https://api.bitsighttech.com/ratings/v1/companies</href>
        <name>Companies</name>
        </list-item>
        <list-item>
            <href>https://api.bitsighttech.com/ratings/v1/industries</href>
            <name>Industries</name>
        </list-item>
        <list-item>
            <href>https://api.bitsighttech.com/ratings/v1/alerts</href>
            <name>Alerts</name>
        </list-item>
        <list-item>
            <href>https://api.bitsighttech.com/ratings/v1/subscriptions</href>
            <name>Subscriptions</name>
        </list-item>
    </resources>
    <disclaimer>This API contains sensitive information intended only for authorized viewers. All content is the property of Bitsight and cannot be shared, copied, or distributed without the express permission of Bitsight. Use of this data must adhere to the Bitsight Terms of Service.</disclaimer>
</root>

Alternate Accept Header: X-Bitsight-Accept

If your integration systems can't use the regular Accept header (you are an Archer system user, for instance), use the X-Bitsight-Accept header in place of the normal Accept header for the exact same functionality.

See the Integrations directory for additional integrations details.

Example Request

curl https://api.bitsighttech.com/ratings/v… -u api_token: -H "X-Bitsight-Accept: application/xml"

This is case-sensitive. When troubleshooting, ensure the capitalization of the X-Bitsight-Accept header is correct.

Versioning

To specify an API version, include the version in in the URL (e.g., https://api.bitsighttech.com/ratings/v1/…). To learn about our API versions, visit the API Change Log.

A new version will be released for:

  • Fundamental changes to the JSON format.
  • Variable type changes.
  • Backwards incompatible changes.

A new version will not be released for:

  • Additional fields in the JSON.
  • New API resources.
  • New finding (events and records) types.
  • New optional parameters to existing API methods.
  • New properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of object IDs or other opaque strings.
  • Backwards compatible changes.

Support and Deprecation

Older versions will be unsupported and will no longer receive any updates. They will be available for a time before they are fully deprecated.

Related articles