Parameters

Use the following parameters to navigate the Bitsight API. Available parameters vary depending on the endpoint.

Path Parameters

Uses a part of the URL as a parameter.

Example:

curl "https://api.example.com/guid/endpoint"

GUID Types

Path parameters are often unique identifiers (GUID) of a particular data set.

account_guid

Your Bitsight account unique identifier.

Values: See GET: User Details [v1].

alert_guid

Alerts notify you of changes that occur in your portfolio and changes to risk vector grades.

Values: See GET: Alerts.

benchmark_guid

The unique identifier of a benchmark group.

Values: See selected_benchmark_group in GET: Companies in Peer Comparison Group.

company_request_guid

Requests to add companies to the Bitsight inventory.

Values: See GET: Company Requests.

entity_guid

Companies in the Bitsight inventory.

Aliases: company_guid, provider_guid, & country_guid.

Values: See GET: Portfolio Details.

folder_guid

Folders can be used to organize your portfolio to better understand the security performance of certain groups of companies.

Values: See GET: Folder Details.

group_guid

Access Control Groups allow subsets of portfolio companies to be grouped together and users to be assigned access to them. The users will have the ability to see and monitor only the subset of companies.

Values: See GET: Access Control Groups.

peer_guid

The unique identifier of a peer group.

Values: See selected_peer_group in GET: Companies in Peer Comparison Group.

product_guid

Service provider products include their service offerings, such as web hosting, certificate signing, cloud infrastructure services, email hosting, etc.

Values: See GET: Products of a Company.

relationship_guid

Company relationships can be defined to optimize the onboarding workflow by applying the appropriate level of due diligence to a company while they’re being evaluated during onboarding.

Values: See GET: Company Relationship Details.

tag_guid

Infrastructure tag, which is used to define and provide context on assets.

Values: See tag_details:guid using GET: Assets.

template_guid

Assessment Report templates are used to generate assessments.

Values: See GET: Assessment Report Template.

threat_guid

Threats such as vulnerabilities.

Values: See GET: Portfolio Threats.

tier_guid

Tiers are used to prioritize companies in your portfolio based on their criticality to your organization and their security risk.

Values: See GET: Tiers.

user_guid

Users of the Bitsight platform.

Values: See GET: Users.

Query Parameters

Query parameters are used to sort, filter, and limit the response.

Append a question mark (?) to the URL to indicate the start of a query parameter. Additional query parameters are indicated with an ampersand (&), and if present, the URL should be wrapped with double quotes (").

Example:

curl "https://api.example.com/endpoint?field1=value1&field2=value2"

Use comma-separated fields to query multiple values using a single parameter.

Example:

curl "https://api.example.com/endpoint?field1=value1,value2"

cursor

For select endpoints with large datasets, the cursor parameter is included, which is an opaque base64-encoded string that enables navigation to the next or previous page of results. If a query matches few observations and the response contains a cursor but no data, the cursor can then be used to ask the server to continue searching.

Values: [String]

[Date] start_date

Set a start date.

Values: [String] The starting date [YYYY‑MM‑DD] for the date range.

[Date] end_date

Set an end date.

Values: [String] The ending date [YYYY‑MM‑DD] for the date range.

fields

Filter by fields.

Values: [String] Comma-separated field names. Field names are the names of the fields in the response object. The order of the specific fields might not be reflected in the response.

format

Set the format of the response data.

Some parsing tools that can be used to read files in a more human-readable way are available, such as Mozilla Firefox (www.firefox.com), which is able to open and interpret JSON and XML output files and present them in a more polished way.

Values: [String]

• csv – A comma-separated values (CSV) file is a text file that allows data to be saved in a table structured format.
• json – JavaScript Object Notation (JSON) is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays (or other serializable values).
• xml

limit

Set the maximum number of results. The results might include fewer records (even zero), but not more.

Values: [Integer] If not set, the default number of results can vary depending on the endpoint.

next_url

Navigate to the next page of the results.

Values: [String] URL

offset

Set the starting point of the return.

Values: [Integer] A 0 (zero) value starts the results from the first record in the result set.

q

Perform a full-text search for matching records on all searchable fields.

Values: [String]

sort

Sort the response objects in alphabetical order.

Values: [String]

• Field name.
• To sort in descending order, place a minus sign (-) immediately before the field name.

Example:

'field_1,-field_2' first sorts by ascending field_1, and then by descending field_2.