--- title: "Balbix REST API Guide" slug: "balbix-rest-api-guide-v20" updated: 2026-10-22T15:02:22Z published: 2026-10-22T15:02:22Z canonical: "docs.safe.security/balbix-rest-api-guide-v20" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.safe.security/llms.txt > Use this file to discover all available pages before exploring further. # Balbix REST API Guide ### **Overview** About the Balbix REST API Balbix offers a REST API for programmatic access to information about **Assets** and their associated **Vulnerabilities**, **Misconfigurations**, and **Software Inventories, Applications and related Artifacts**. This API is under active development, with many new endpoints and query parameters planned to facilitate a wide range of use cases. ### **Current Limitations** There are a number of limitations to be aware of when using the API: 1. The API is currently **read-only;** it is not possible to modify assets, interact with the UI, upload data, or modify tags via the API, although these features are planned. 2. The API also pulls from a replica database, so a slight delay may occur between live data in the UI and the results retrieved from the API. 3. Although there are no hard-coded rate limits, the API only supports 4 concurrent sessions per customer; new sessions will be processed once previous requests have been handled. 4. The API is not suitable for bulk data exports, but instead for the retrieval of data regarding individual or small numbers of Assets. ### **Requesting API Credentials** Currently, API credentials can only be created by Balbix Engineers & Balbix Customer Success. Credentials are created per customer tenant. A future update to the UI will allow users to create and manage their own credentials. Upon request, Balbix will provide the following to you: 1. The Base URL for your API Endpoints 2. A static Username and Password for initial authentication to the Token endpoint 3. A corresponding Customer Key to be included as a parameter when accessing the Token endpoint 4. A Client API Key which uniquely identifies your specific tenant ### **Using the Balbix REST API** Obtaining a Session Authorization Token All Balbix API endpoints require an **Authorization Token** in conjunction with the **Client API Key**. The Authorization Token is granted by the /apis/v1/gen_token endpoint; these tokens expire after 30 minutes. Unset curl --location --user 'YOUR_USERNAME:YOUR_PASSWORD' 'https://rs005tra.balbix.net/apis/v1/gen_token?key=YOUR_CUSTOMER_KEY #### **Retrieving Device IDs** All Assets in Balbix have a unique identifier known as a **Device ID**. The Device ID ensures that Assets with the same Hostname or IP Address can be uniquely identified. The /asset_list endpoint is designed to take any combination of Hostname, IP Address, and MAC Address to search for a specific Asset. Here is an example of how to combine all three searchable attributes alongside the appropriate headers: Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/asset_list' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "page_offset": 0, "page_limit": 100, "host_name": "BTD-SRV-2016-QA", "ip": "10.1.4.254", "mac": "00:50:56:bc:ff:ff" }' Response: Response has been shortened for documentation to indicate the existence of dev_id { "data": [ { "agent_type": "{\"Amazon Web Services (AWS)\"}", "data_observers":null "dev_id": 12345, "device_subtype": "Excluded", "device_tags": [], "device_type": "Unexamined", "device_zone": null, "final_name": null, "groups": null "host_name": null, "ip": null, "likelihood": null "operatingsystem": null, "os_arch": null, "os_name": null, "os_vendor": null, "os_version": null, "serial_number": null } ], "meta": { "filters": "", "page_limit": 1, "page_offset": 0, "sort": "", "total_count": 1500 } } If the provided parameters match multiple Assets, those Assets will be returned in a list. The specific Device ID can be found in the response by searching for “dev_id” - Unset "dev_id": 12345, #### **Making API Calls with Device ID** Given a specific Device ID, Balbix offers four API endpoints which can be used to retrieve information about an Asset: 1. Asset Details 2. Vulnerabilities 3. Misconfigurations 4. Software Details Retrieving Asset Details with Device ID Returns all Attributes for a given Asset; does not implement pagination as only a single result is expected. Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/asset_details/DEVICE_ID' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json' Response: Sample Response has been shortened for documentation to indicate the existence of details { "data": { "agent_type": "{\"Amazon Web Services (AWS)\"}", "created_at": null, "data_observers": null "dev_id": 12345, "device_guid": null, "device_roles": null, "device_subtype": "Excluded", "device_tags": [], "device_type": "Unexamined", "groups": [ "All Assets" ], "host_name": null, "impact": 0.0, "interfaces": [], "ip": null, "likelihood": null "mac": null, "operatingsystem": null, "os_arch": null, "os_name": null, "os_vendor": null, "os_version": null, "serial_number": null, "site_name": null, "smbios_version": null, "system_manufacturer": null, "system_model": null, "total_physical_mem_mb": null, "unique_identifier": null, } } #### **Retrieving Vulnerabilities with Device ID** Returns all Vulnerabilities for a given Asset. Implements pagination up to 1000 results. Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/vulns/DEVICE_ID \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "page_offset": 0, "page_limit": 1000, }' Response { "data": [ { "id": "123f280f-3e66-5288-b53c-95dce2f9a1f3", "attck": [ "TA0040<-->T1499", "TA0002" ], "balbix_device_subtype": "", "balbix_device_type": "", "component_instance_id": "ccfdaccc-588f-5ea7-a505-8f23bdc55920", "component_name": "Tomcat", "component_state": "UNPATCHED", "component_tracking_id": null, "component_type": "", "component_version": "v1", "components": null, "consolidated_components": [], "consolidated_vulns": [], "cpe": "", "created_at": null, "cve_id": "", "cvss_score": null, "cvss_severity": 0.0, "cwe_id": [], "data_sources": null, "description": null, "dev_id": 1234, "exposure_score": 78.0, "exposure_severity": "HIGH", "first_seen": null, "fixes": [], "mitre_attck_id": "", "vuln_first_detected_at": null, "vuln_instance_created_at": null, "vuln_instance_details": "", "vuln_instance_detection_method": "", "vuln_instance_mitigated_at": null, "vuln_instance_state": "", "vuln_name": "CVE-2024-50379", "vuln_published_date": null, "vuln_tags": null, "vuln_tracking_id": "", "vuln_type": "CVE", } ], "meta": { "filters": "", "page_limit": 1, "page_offset": 0, "sort": "", "total_count": 1000 } } #### **Retrieving Misconfigurations with Device ID** Returns all Misconfigurations for a given Asset. Implements pagination up to 100 results. Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/misconfig_details/DEVICE_ID \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "page_offset": 0, "page_limit": 100, }' Response: "data": [ { "id": "123f280f-3e66-5288-b53c-95dce2f9a1f3", "component_instance_id": "ccfdaccc-588f-5ea7-a505-8f23bdc55920", "component_name": "Tomcat", "component_state": "UNPATCHED", "component_type": "", "component_version": "v1", "cve_id": "", "cvss_score": null, "cvss_severity": 0.0, "cwe_id": [], "dev_id": 1234, "exposure_score": 78.0, "exposure_severity": "HIGH", "first_seen": null, "fixes": [], "vuln_first_detected_at": null, "vuln_instance_state": "", "vuln_name": "Sample custom Vuln", "vuln_published_date": null, "vuln_tags": null, "vuln_tracking_id": "", "vuln_type": "NON-CVE", } ], "meta": { "filters": "", "page_limit": 1, "page_offset": 0, "sort": "", "total_count": 1000 } } #### **Retrieving Software Details with Device ID** Returns all Software Inventory for a given Asset, including Operating System. Implements pagination up to 100 results. Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/sw_details/DEVICE_ID \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "page_offset": 0, "page_limit": 100, }' Response: "data": [ { "bomRef": "", "category": "", "componentInstanceId": "1234a71f-5393-5d12-803d-835ea937c5f0", "componentState": "UNPATCHED", "dataSources": [ "Defender" ], "installPath": "C:\\Users\\sample\\AppData\\Local\\Programs\\Python\\Python310\\python.exe", "installTime": null, "name": "Python", "product": "Python", "type": "APPLICATION", "vendor": "Python", "version": "3.10.0.0", } ], "meta": { "filters": "", "page_limit": 1, "page_offset": 0, "sort": "", "total_count": 1000 } } #### **Retrieveing Application IDs** All applications in Balbix have a unique identifier known as Application ID. The Application ID ensures that applications with the same name or alias or url can be uniquely identified. The app_list end point is designed to take any combination of appname, app_id, or app_url to search for a specific Application. Here is an example of how to combine all three searchable attributes alongside the appropriate headers: Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/app_list' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "page_offset": 0, "page_limit": 100, "application_name": "Business Application", "application_id": "BTD-1234" "app_url": "www.testapp.com" }' Response:Response has been shortened for documentation to indicate the existence of app_id { "data": [ { "data_observers":null "app_id": 6815282, "app_tags": [], "app_type": "Unexamined", "application_name": null } ], "meta": { "filters": "", "page_limit": 1, "page_offset": 0, "sort": "", "total_count": 26954 } } If the provided parameters match multiple Applications, those Applications will be returned in a list. The specific App ID can be found in the response by searching for app_id Unset "app_id": 17092777 #### **Making API Calls with App ID** Given a specific App ID, Balbix offers 4 API endpoints which can be used to retrieve information about an Application: 1. Application Details 2. Application Artifacts 3. Vulnerabilities 4. Application Infrastructure Assets Retrieving Application Details with App ID Returns all Attributes for a given Applications; does not implement pagination as only a single result is expected. Here is an example of an application: Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/app_details/APP_ID' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json Response: Response has been shortened for documentation to indicate few application details { "name": "Sample Application", "app_id": 1234, "alias": "", "application_id": "APP1234", "application_owner": "", "business_criticality": null, "business_owner": "No Owner", "data_sources": null, "infrastructure": [ { "dev_id": 12345 } ], "repository_type": null, "repository": null, "url": "https://sample.com" } #### **Retrieving Application Artifacts with App ID** Returns all Application artifacts like repositories, projects, deployments for a given Application. Implements pagination up to 100 results. Here is an example of application related artifacts: Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/artifacts/APP_ID \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "page_offset": 0, "page_limit": 100, }' Response:Response has been shortened for documentation to indicate the existence of sample Artifacts { "data": [ { "name": "Sample Artifact", "app_id": 1234, "tags":null, "dataSources": [ "SAST", "SCA" ], "repository": null, "repository_tyype": null, "maxExposure": 72, ], "meta": { "filters": "", "page_limit": 1, "page_offset": 0, "sort": "", "total_count": 1500 } } #### **Retrieving Vulnerabilities with App ID** Returns all Vulnerabilities for a given Application. Implements pagination up to 1000 results.: Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/vulns/APP_ID \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "page_offset": 0, "page_limit": 1000, }' Response:Response has been shortened for documentation to indicate the existence of sample vulnerabilities { "data": [ { "id": "", "assessment_type": "SCA", "app_id": 1234, "component_id": "", "component_name": null, "component_page_name": null, "component_page_path": null, "component_type": "DEPENDENCY", "component_version": "", "created_at": "", "cve_severity": 0, "cvss_score": 0.0, "cvss_severity": 0.0, "cwe_id": [], "cwe_ids": [], "data_sources": null, "first_seen": null, "fixes": [], "name": null, "project_names": [], "projects": [], "url": [], "vm_owner": "No Owner", "vuln_description": "Sample vuln Description", "vuln_details": null, "vuln_name": "Sample vuln", "vuln_tags": null, "vuln_type": "cve", } ], "meta": { "filters": "", "page_limit": 1, "page_offset": 0, "sort": "", "total_count": 1500 } } #### **Retrieving Infrastructure Asset by App ID** Returns all infrastructure assets for a given Application. Implements pagination up to 100 results. Unset curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/infra-assets/APP_ID' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --header 'Client-API-Key: YOUR_CLIENT_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "page_offset": 0, "page_limit": 100 }' Response: Response has been shortened for documentation to indicate few details about infrastructure assets { "data": [ { "agent_type": "{\"Amazon Web Services (AWS)\"}", "data_observers":null "dev_id": 12345, "device_subtype": "Excluded", "device_tags": [], "device_type": "Unexamined", "device_zone": null, "final_name": null, "groups": null "host_name": null, "ip": null, "likelihood": null "operatingsystem": null, "os_arch": null, "os_name": null, "os_vendor": null, "os_version": null, "serial_number": null } ], "meta": { "filters": "", "page_limit": 1, "page_offset": 0, "sort": "", "total_count": 1500 } } \