Skip to main content

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 admin button > 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:

    • GraphQL Documentation Explorer icon: Displays the schema of each object.

    • GraphQL History icon: Displays the history of your executed queries.

    • GraphQL Code Exporter icon: Displays the cURL command of your query.

    • GraphQL Explorer icon: 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

FormatDescriptionExamples
TimestampA 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-YYYYA 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
UTCA 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

ExpressionDescription
nowCurrent date and time
todayCurrent date and time
yesterdayYesterday at current date and time
-3mCurrent time minus three minutes (three minutes in the past)
+3mCurrent time plus three minutes (three minutes in the future)
-2hCurrent date and time minus 2 hours
+1hCurrent date and time plus 1 hour
-5dCurrent date and time minus 5 days
+7dCurrent date and time plus 7 days
-3wCurrent date and time minus three weeks
+3wCurrent date and time plus three weeks
-6MCurrent date and time minus 6 months
+1MCurrent date and time plus 1 month
-2yCurrent date and time minus two years
+2yCurrent 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

OperatorSyntaxExamples
BeforeBEFORE datedateCreated BEFORE yesterday,
lastUpdated BEFORE 09-06-2025
BetweenBETWEEN [date1, date2]dateCreated BETWEEN [-2d, now],
firstFound BETWEEN [01-01-2025, 01-31-2025T23:59:59.999Z]
In LastIN_LAST relative-datedateCreated IN_LAST 3d (e.g.: hosts created in the last 3 days)
In NextIN_NEXT relative-datedueDate IN_NEXT 1M (e.g.: tickets dued in the next month)
IsIS datelastUpdated IS 09-06-2025T23:59:59.999Z
Not BetweenNOT_BETWEEN [date1, date2]firstFound NOT_BETWEEN [01-01-2025, 01-31-2025T23:59:59.999Z]
Not In LastNOT_IN_LAST relative-datedateCreated NOT_IN_LAST 1d (e.g.: vulnerabilities not created in the last day)
Not In NextNOT_IN_NEXT relative-datedue_date NOT_IN_NEXT 3h (e.g.: tickets not dued in the next 3 hours)
Not IsNOT_IS datelastUpdated NOT_IS 09-06-2025T23:59:59.999Z
SinceSINCE datelastUpdate 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 ProblemSuggestion
401 UnauthorizedThe access token has expired
403 ForbiddenThe user doesn't have permissions to access that endpoint
404 Not FoundMay mean that the data Model was incorrectly specified
405 Not AcceptableMay mean that a parameter was incorrect. Check for a message in the response.
Response comes back with HTMLThe URI may be missing the /api component