System Detection API

The System Detection API was built to enable DataGrail customers to add systems to their inventory, particularly from internal services or other sources that catalog internal systems.

API Conventions

All URLs listed in the documentation should have the same base URL that precedes each route. This consists of your organization's DataGrail URL along with the API version:

https://${yoursubdomain.datagrail.io}/api/v2

Authorization

In order to use this API, you must first set up an RDD agent. An agent's associated API key is required to authenticate and authorize requests to this API. The API key will be required as a bearer token in the Authorization header.

Add Systems to Inventory

POST Name and information that identifies a system or vendor and provides additional context or metadata to help DataGrail's system detection capabilities to disambiguate the types of systems or vendors that are matched in the DataGrail catalog. For example, you may have multiple MySQL instances. Each of those will have a unique name (some identifying label), but you'll ultimately wish to identify it as a MySQL type. The label may not identify the type, so it's important to share additional context that may help in identifying this as a MySQL type. This may include labels, tags, Docker image names or other information that has a common identifier for a system type. In other instances, you may have proprietary or custom systems that won't be matched to DataGrail's catalog, but may wish to still add to your inventory in order to manage records of processing activities or impact assessments within the DataGrail platform.

Endpoint

POST /system_detection/detected_objects

API Parameters

Parameter	Parameter Type	Type	Required	Description
Authorization	Header	string	True	Bearer token
source	Body	string	True	The name of the source of information for detected systems
detected_objects	Body	Array[DetectedObject]	True	A JSONArray of DetectedObjects (defined below)

DetectedObject

Field	Type	Required	Description
label	string	True	The name or identifier of a system/instance/vendor
metadata	object	True	Additional context or metadata about the object scanned to aid in matching to known systems or vendors during data mapping
created_at	string	False	The datetime of a scan or an approximation of when the system was first detected

Example

curl -XPOST "https://${yoursubdomain.datagrail.io}/api/v2/system_detection/detected_objects" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
      "source": "kubernetes",
      "detected_objects": [
        {
          "label": "db-prod-service001",
          "metadata": {
            "namespace": "production",
            "image": "mysql:8.4.0",
            "container_name": "mysql-prod",
          }
        }
      ]
  }'

Example 200 - OK Response

{}

Error Codes

This API uses the following error codes:

Code	Description
401	Unauthorized -- Your API key is incorrect or invalid.
404	Not Found -- The integration could not be found. Confirm the route or integration id are correct.
422	Unprocessable Entity -- The request body cannot be processed. Ensure that you're passing the correct parameters.
500	Internal Server Error -- An internal and unexpected error condition occurred.