Brinqa Platform API

This article provides instructions on authenticating with the Brinqa Platform application programming interface (API) and how to run queries using the built-in GraphQL Explorer.

Overview

The Brinqa Platform API allows for flexible interactions with the Brinqa Platform, offering a powerful way to extract and manipulate your data to better serve your needs. It uses GraphQL as the query language to interact with the Brinqa Platform API, providing an efficient and performance-friendly method to specify and retrieve the exact data you need.

GraphQL allows you to specify exactly what data you need and receive that data in a single request. To make it even easier to work with, Brinqa includes a GraphQL Explorer, which is an in-browser integrated development environment (IDE) for writing, validating, and testing GraphQL queries. You can use this tool to explore the objects made available by the Brinqa API and build your queries with just a few clicks.

How to use the GraphQL explorer

To access the GraphQL Explorer, you must log in to your Brinqa Platform as a Data Exporter or System Administrator. After you've logged in, navigate to Administration > System > GraphQL Explorer.

note

While the Data Exporter role allows you to export data from the GraphQL Explorer, you must have additional roles that provide permissions to access the data, such as Administrator, Remediation owner, or Risk owner. For additional information on role permissions, please see the Roles documentation.

You can type your query directly or use the icons on the left-hand side to access various explorers for additional assistance. The IDE consists of three panes:

Left pane: Displays different content based on which icon you've selected:
- : Displays the schema of each object.
- : Displays the history of your executed queries.
- : Displays the cURL command of your query.
- : Displays the list of objects and fields that you can use to build your query.
  
  info
  While you can select the conditions attribute in the GraphQL Explorer, it is currently not supported. Please use other filtering options to refine your queries.
Middle pane: Displays the query formed automatically after you've selected the fields.
Right pane: Displays the result after you've executed the query.

For specific examples of how to use the GraphQL explorer to retrieve different datasets, see the following articles:

Important

GraphQL is specifically designed for querying less than 5,000 datasets and is not intended for bulk exports or as a bulk API. Typical usage should involve queries designed to display between 100 to 200 entries. For bulk data exports, please utilize Brinqa Connect.

Applying Date Filters in the GraphQL Explorer

In the GraphQL Explorer, you can filter by date using a timestamp, the MM-DD-YYYY format, or Coordinated Universal Time (UTC). See the table below for examples.

Table 1. Supported Date Formats

Format	Description	Examples
Timestamp	A way of representing a specific point in time as a single number, usually the number of milliseconds since a fixed starting point called the "epoch."	1751827200000 (September 6, 2025 in milliseconds since epoch)
MM-DD-YYYY	A common way to represent dates in the United States. It stands for: MM = two-digit month (01–12) DD = two-digit day of the month (01–31) YYYY = four-digit year	09-06-2025 09-6-2025 9-6-2025
UTC	A date-time string in ISO 8601 format that ends with the letter Z, which stands for "Zulu time" (another name for UTC time). For example, 2025-09-06 = date (YYYY-MM-DD) T = separator 00:00:00 = time (HH:MM:SS) Z = Zulu time (UTC)	2025-09-06T00:00:00.000Z 2025-9-06T00:00:00.000Z 2025-9-6T00:00:00.000Z 2025-9-6T0:00:00.000Z 2025-9-6T0:0:00.000Z 2025-9-6T0:0:0.0Z 2025-9-6T0:0:0Z

In addition, you can use relative date expressions in your filters, as shown in the following table.

Table 2. Supported Relative Date Expressions

Expression	Description
now	Current date and time
today	Current date and time
yesterday	Yesterday at current date and time
-3m	Current time minus three minutes (three minutes in the past)
+3m	Current time plus three minutes (three minutes in the future)
-2h	Current date and time minus 2 hours
+1h	Current date and time plus 1 hour
-5d	Current date and time minus 5 days
+7d	Current date and time plus 7 days
-3w	Current date and time minus three weeks
+3w	Current date and time plus three weeks
-6M	Current date and time minus 6 months
+1M	Current date and time plus 1 month
-2y	Current date and time minus two years
+2y	Current date and time plus two years

Lastly, you can use date operators with attributes of type Date, DateTime, Time, or with calculated attributes that return these types. Both absolute and relative dates are supported. The following table summarizes the date operators available for GraphQL queries.

Table 3. Supported Date Operators

Operator	Syntax	Examples
Before	BEFORE `date`	`dateCreated BEFORE yesterday`, `lastUpdated BEFORE 09-06-2025`
Between	BETWEEN `[date1, date2]`	`dateCreated BETWEEN [-2d, now]`, `firstFound BETWEEN [01-01-2025, 01-31-2025T23:59:59.999Z]`
In Last	IN_LAST `relative-date`	`dateCreated IN_LAST 3d` (e.g.: hosts created in the last 3 days)
In Next	IN_NEXT `relative-date`	`dueDate IN_NEXT 1M` (e.g.: tickets dued in the next month)
Is	IS `date`	`lastUpdated IS 09-06-2025T23:59:59.999Z`
Not Between	NOT_BETWEEN `[date1, date2]`	`firstFound NOT_BETWEEN [01-01-2025, 01-31-2025T23:59:59.999Z]`
Not In Last	NOT_IN_LAST `relative-date`	`dateCreated NOT_IN_LAST 1d` (e.g.: vulnerabilities not created in the last day)
Not In Next	NOT_IN_NEXT `relative-date`	`due_date NOT_IN_NEXT 3h` (e.g.: tickets not dued in the next 3 hours)
Not Is	NOT_IS `date`	`lastUpdated NOT_IS 09-06-2025T23:59:59.999Z`
Since	SINCE `date`	`lastUpdate SINCE 1523544660507`

Obtain an API token

Before you can use the Brinqa Platform API, you need to authenticate your requests. The Brinqa Platform API uses bearer token authentication to verify the identity of the user making the request. To interact with the API and perform operations such as running queries or retrieving data, you must first obtain an access token.

To get your access token, use the following cURL command:

curl --location --request POST 'https://<your-brinqa-platform-url>/api/auth/login' \
--header 'Accept: application/json' \
--header 'X-Requested-With: XMLHttpRequest' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "<your-username>",
    "password": "<your-password>"
}'

In this command, replace <your-brinqa-platform-url>, <your-username>, and <your-password> with your Brinqa Platform URL and login information. This token grants the same permissions as the user's access within the Brinqa Platform. If a user's access in the Brinqa Platform is limited to a certain subset of data, their API access will also be limited to that subset.

<your-password> is the password assigned to the user record in the Brinqa Platform. In case your user is configured with single sign-on (SSO) authentication, you can edit the user record and set a password specifically for token generation. Alternatively, you can create a new user designated to generate tokens. Either way, your SSO username and password remain unaffected.

If you have multi-factor authentication (MFA) enabled, add this line at the end of the cURL command: "code": "<your-mfa-code>". So the full cURL command would read:

curl --location --request POST 'https://<your-brinqa-platform-url>/api/auth/login' \
  --header 'Accept: application/json' \
  --header 'X-Requested-With: XMLHttpRequest' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "username": "<your-username>",
    "password": "<your-password>",
    "code": "<your-mfa-code>"
},

In this command, replace <your-mfa-code> with the authenticator code generated by your organization's authenticator app.

Upon successful authentication, you will receive a response similar to the following that includes your access token:

{
    "username": "<your-username>",
    "token_type": "Bearer",
    "access_token": "<your-access-token>",
    "expires_in": 86400,
    "refresh_token": ""
}

Copy <your-access-token> value. This token is what you will use to authenticate your requests when you execute queries.

Execute Brinqa API queries

After obtaining the access token from the auth/login endpoint, insert it into your cURL command like so:

curl 'https://<your-brinqa-platform-url>/graphql/caasm' \
--compressed \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-access-token>" \
-H "Accept: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-H "Accept-Encoding: gzip, deflate" \
--data '{ 
  "query": "query MyQuery {  assets(filter: "status=active", limit: 5) {    complianceStatus    displayName    firstSeen    id    lastUpdated    status  }}",
  "variables": null,
  "operationName": "MyQuery"
}'

The access token is valid for 86400 seconds, or 24 hours. After it expires, you can generate a new token by following the same step.

Error code descriptions

Here are some common error codes and their meanings that you might encounter while working with the Brinqa Platform API:

Error Code or Problem	Suggestion
401 Unauthorized	The access token has expired
403 Forbidden	The user doesn't have permissions to access that endpoint
404 Not Found	May mean that the data Model was incorrectly specified
405 Not Acceptable	May mean that a parameter was incorrect. Check for a message in the response.
Response comes back with HTML	The URI may be missing the `/api` component

Overview​

How to use the GraphQL explorer​

Applying Date Filters in the GraphQL Explorer​

Obtain an API token​

Execute Brinqa API queries​

Error code descriptions​