Get Started

This guide provides a practical introduction to the Google Threat Intelligence 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 REST API Reference.

Prerequisites

Before you begin, ensure you have the following:

  1. 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%2Fyour-project-id, the Project ID is your-project-id), or contact your account team if you cannot find it. Enter your org's Project ID here: YOUR_ORG_PROJECT_ID
  2. 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
}

Copy the access_token from the response and enter it here: YOUR_ACCESS_TOKEN

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.

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"

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 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"