Get Started

This guide provides a practical introduction to the 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 own Google Cloud Project. Enter your Project ID here: YOUR_PROJECT_ID
2. The Threat Intelligence API enabled for your project.
   Enable the API
3. The gcloud CLI installed and authenticated to your project.
4. Your organization's Google Cloud Project, provisioned and assigned to you by the Google Threat Intelligence team. Enter your org's Project ID here: YOUR_ORG_PROJECT_ID

Authentication

The API requires OAuth 2.0 authentication. The easiest way to obtain an access token for testing is via the gcloud CLI, which the examples below generates inline.

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 a all alerts for your project.

curl -H "x-goog-user-project: YOUR_PROJECT_ID" \
     -H "Authorization: Bearer $(gcloud auth print-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_PROJECT_ID" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/alerts/ALERT_ID"
    

Working with 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_PROJECT_ID" \
     -H "Authorization: Bearer $(gcloud auth print-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 response from the List Configurations call.
curl -H "x-goog-user-project: YOUR_PROJECT_ID" \
     -H "Authorization: Bearer $(gcloud auth print-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 Org 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_PROJECT_ID" \
     -H "Authorization: Bearer $(gcloud auth print-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_PROJECT_ID" \
     -H "Authorization: Bearer $(gcloud auth print-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_PROJECT_ID" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://threatintelligence.googleapis.com/v1beta/projects/YOUR_ORG_PROJECT_ID/findings/FINDING_ID"