🚧
Beta
Google Threat Intelligence Alerts API is provided as a beta feature and is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms, and the Additional Terms for Generative AI Preview Products. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This guide provides a practical introduction to the Google Threat Intelligence Alerts API. You will learn how to authenticate and perform basic operations against Alerts, Findings, and Configurations using standard HTTP requests. For detailed API documentation, see the Threat Intelligence API.

Prerequisites

Before you begin, ensure you have the following:

Your organization's Google Cloud Project ID, which is assigned by the Google Threat Intelligence team when your organization is onboarded. You can find this ID in the URL when accessing GTI Alerts (for example, in https://proactive.virustotal.com/alerts?...&project=projects%2F**your-project-id**, the Project ID is your-project-id), or contact your account team if you cannot find it.
A GTI API key, which you can find in the GTI UI under Profile > API Key.

Authentication

The API requires OAuth 2.0 authentication. You can exchange your GTI API key for an access token using the following endpoint:

curl https://idp.prod.identity.proactive.virustotal.com/realms/master/exchange/api-key \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}'

The response will contain the access token and its expiration time (usually 4 hours).

{
  "access_token": "ya29.d.s0Ad...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 14398
}

Working with Alerts

Alerts are the primary actionable units in the system. They represent consolidated groups of findings that require your attention.

List Alerts

Retrieve all alerts for your project. Note by default, the alerts returned are unordered.

curl -H "x-goog-user-project: YOUR_ORG_PROJECT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/alerts"

List Alerts with Filtering and OrderBy

Retrieve a filtered list of alerts for your project and order the results.

The following example only filters for the data_leak alert detail type with a HIGH severity, and orders the results by create time with latest alerts first. For more filtering and ordering options with examples, see the List Alerts API reference.

curl -G \
     -H "x-goog-user-project: YOUR_ORG_PROJECT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     --data-urlencode 'filter=((detail.data_leak.severity="HIGH"))' \
     --data-urlencode 'orderBy=audit.create_time desc' \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/alerts"

Get an Alert

Retrieve full details for a specific alert using its resource ID. This includes the generated summary, severity scores, and status. You can get the resource ID from the name field in the response from the List Alerts call.

# Replace ALERT_ID with the specific ID. 
curl -H "x-goog-user-project: YOUR_ORG_PROJECT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/alerts/ALERT_ID"

Working with Organization Profile via Configurations

Configurations hold your Organization Profile, which defines what the system matches for.

List Configurations

See all configurations associated with your project.

curl -H "x-goog-user-project: YOUR_ORG_PROJECT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/configurations"

Get a Configuration

View the details of a specific configuration, such as your defined profiles and threat scenarios.

# Replace CONFIG_ID with the specific ID. You can get the ID from the name field in the response from the [List Configurations](#list-configurations) call.
curl -H "x-goog-user-project: YOUR_ORG_PROJECT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/configurations/CONFIG_ID"

Upsert a Configuration

Create or update a configuration. The example below shows how to add a new product, YouTube, to an existing Organization Profile that currently only includes Google Cloud. You can replace each of the fields in the example below with your own values from the List Configurations call above.

# Replace CONFIG_ID with the specific ID.
curl -X POST -H "x-goog-user-project: YOUR_ORG_PROJECT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "projects/YOUR_ORG_PROJECT_ID/configurations/CONFIG_ID",
       "provider": "GTI Alerts",
       "state": "ENABLED",
       "detail": {
         "customerProfile": {
           "org": "Google",
           "products": [
             {
               "product": "Cloud",
               "brand": "Google Cloud"
             },
             {
               "product": "Video Platform",
               "brand": "YouTube"
             }
           ]
         }
       }
     }' \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/configurations:upsert"

Working with Findings

Findings are the raw pieces of evidence (e.g., a specific forum post or leaked credential) that are aggregated into Alerts.

List Findings

Retrieve all findings for your project.

curl -H "x-goog-user-project: YOUR_ORG_PROJECT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/findings"

Get a Finding

Get the complete technical details of a specific finding. You can get the ID from the name field in the response from the List Findings call.

# Replace FINDING_ID with the specific ID.
curl -H "x-goog-user-project: YOUR_ORG_PROJECT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/findings/FINDING_ID"