Threat Intelligence
API Reference

Endpoint Structure

https://api.threatintel.example.com/v1/{resource}

All requests must be made over HTTPS. Plain HTTP requests return 301 Moved Permanently. All endpoints return application/json by default. Pass Accept: application/stix+json to receive STIX 2.1 formatted output for downstream tool integration.

API Key Authentication

All API requests require a valid API key passed as a request header. Keys are scoped to a subscription tier and carry rate limits accordingly.

Required Header

X-API-Key: your_api_key_here

Obtaining an API Key

1. Log in to the Threat Intelligence Portal at portal.threatintel.example.com
2. Navigate to Settings → API Access
3. Select Generate New Key
4. Copy and securely store your key — it is displayed only once

Authentication Error Codes

Request Limits by Tier

Requests are rate-limited per API key on a rolling 60-second window. When a limit is exceeded the API returns 429 Too Many Requests with the following response headers.

Rate Limit Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711670400
Retry-After: 47

GET /indicators/{type}/{value}

curl -X GET \
  "https://api.threatintel.example.com/v1/indicators/ip/198.51.100.42?include_context=true" \
  -H "X-API-Key: $API_KEY" \
  -H "Accept: application/json"

{
  "status": "success",
  "indicator": {
    "type": "ip",
    "value": "198.51.100.42",
    "first_seen": "2025-11-03T08:14:22Z",
    "last_seen": "2026-03-15T17:42:09Z",
    "confidence": 94,
    "classification": "malicious",
    "severity": "critical",
    "threat_types": ["command-and-control", "data-exfiltration"],
    "associated_malware": ["POWERSTATS", "AshTag"],
    "attack_techniques": [
      {
        "technique_id": "T1071.001",
        "technique_name": "Application Layer Protocol: Web Protocols",
        "tactic": "Command and Control"
      },
      {
        "technique_id": "T1041",
        "technique_name": "Exfiltration Over C2 Channel",
        "tactic": "Exfiltration"
      }
    ],
    "context": {
      "threat_actor": "Boggy Serpens",
      "aliases": ["MuddyWater", "G0069", "TA450"],
      "campaign": "Operation Silent Harvest",
      "target_sectors": ["Government", "Defense", "Energy"],
      "target_regions": ["Middle East", "North Africa"],
      "actor_motivation": "Espionage"
    },
    "tags": ["apt", "nation-state", "c2", "persistent-threat"],
    "references": [
      "https://unit42.paloaltonetworks.com/boggy-serpens",
      "https://attack.mitre.org/techniques/T1071/001"
    ]
  },
  "meta": {
    "query_time_ms": 38,
    "api_version": "1.0",
    "timestamp": "2026-03-28T10:05:33Z"
  }
}

POST /indicators/bulk

curl -X POST \
  "https://api.threatintel.example.com/v1/indicators/bulk" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "indicators": [
      { "type": "ip",     "value": "198.51.100.42" },
      { "type": "domain", "value": "malicious-c2.example.net" },
      { "type": "hash",   "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }
    ],
    "include_context": false
  }'

{
  "status": "success",
  "total_queried": 3,
  "total_matched": 2,
  "results": [
    { "type": "ip",     "value": "198.51.100.42",             "classification": "malicious", "severity": "critical",       "confidence": 94 },
    { "type": "domain", "value": "malicious-c2.example.net",    "classification": "malicious", "severity": "high",           "confidence": 87 },
    { "type": "hash",   "value": "e3b0c44298fc1c149afb...", "classification": "unknown",   "severity": "informational", "confidence": 0  }
  ],
  "meta": { "query_time_ms": 112, "api_version": "1.0", "timestamp": "2026-03-28T10:07:15Z" }
}

GET /actors/{actor_name}

curl -X GET \
  "https://api.threatintel.example.com/v1/actors/boggy_serpens" \
  -H "X-API-Key: $API_KEY"

{
  "status": "success",
  "actor": {
    "name": "Boggy Serpens",
    "aliases": ["MuddyWater", "G0069", "TA450", "Mango Sandstorm", "MERCURY"],
    "origin": "Iran",
    "attribution": "Ministry of Intelligence and Security (MOIS)",
    "motivation": "Espionage",
    "active_since": "2017",
    "last_activity": "2026-03",
    "target_sectors": ["Government", "Defense", "Telecommunications", "Energy"],
    "target_regions": ["Middle East", "Europe", "North America"],
    "primary_tooling": ["POWERSTATS", "DCHSpy", "MoriAgent", "AshTag"],
    "techniques": [
      { "technique_id": "T1566.001", "technique_name": "Phishing: Spearphishing Attachment", "tactic": "Initial Access",  "frequency": "high"   },
      { "technique_id": "T1053.005", "technique_name": "Scheduled Task/Job",                 "tactic": "Persistence", "frequency": "high"   },
      { "technique_id": "T1059.001", "technique_name": "PowerShell",                          "tactic": "Execution",  "frequency": "medium" }
    ],
    "campaigns": [
      {
        "name": "Operation Silent Harvest",
        "period": "2025-Q3 to present",
        "description": "Cyberespionage campaign targeting Middle Eastern government entities using enhanced social engineering and the AshTag malware suite."
      }
    ],
    "references": [
      "https://unit42.paloaltonetworks.com/boggy-serpens",
      "https://attack.mitre.org/groups/G0069"
    ]
  }
}

GET /search

curl -X GET \
  "https://api.threatintel.example.com/v1/search?q=ransomware&type=indicator&classification=malicious&since=2026-01-01&limit=10" \
  -H "X-API-Key: $API_KEY"

Core Response Fields

HTTP Status Codes

All error responses follow a consistent structure per IETF RFC 7807 Problem Details, returning a JSON body with status, error.code, error.message, and optional error.details fields.

{
  "status": "error",
  "error": {
    "code":    "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded for your subscription tier.",
    "details": "Wait 47 seconds before retrying. Upgrade to Professional for higher limits."
  },
  "meta": { "api_version": "1.0", "timestamp": "2026-03-28T10:00:00Z" }
}

Python — Single IOC Lookup

import requests
import os

API_KEY  = os.environ.get("THREAT_INTEL_API_KEY")
BASE_URL = "https://api.threatintel.example.com/v1"


def get_indicator(indicator_type: str, value: str, include_context: bool = False) -> dict:
    """
    Query threat intelligence for a single indicator of compromise.

    Args:
        indicator_type: One of 'ip', 'domain', 'url', 'hash', 'email'
        value:          The indicator value to query
        include_context: When True, includes full threat actor profile and campaign data

    Returns:
        dict: API response containing threat intelligence enrichment data

    Raises:
        requests.HTTPError:  For 4xx / 5xx responses
        requests.Timeout:    If the request exceeds the timeout threshold
    """
    url     = f"{BASE_URL}/indicators/{indicator_type}/{value}"
    headers = {"X-API-Key": API_KEY}
    params  = {"include_context": str(include_context).lower()}

    response = requests.get(url, headers=headers, params=params, timeout=10)
    response.raise_for_status()
    return response.json()


# Example usage
result    = get_indicator("ip", "198.51.100.42", include_context=True)
indicator = result["indicator"]

print(f"Classification : {indicator['classification']}")
print(f"Severity       : {indicator['severity']}")
print(f"Confidence     : {indicator['confidence']}%")
print(f"Threat Actor   : {indicator['context']['threat_actor']}")

Python — Bulk Lookup with Retry Logic

import time


def bulk_lookup(indicators: list[dict], max_retries: int = 3) -> dict:
    """
    Submit multiple indicators for batch enrichment with automatic retry.

    Args:
        indicators:  List of dicts, each with 'type' and 'value' keys.
                     Maximum 500 indicators per request.
        max_retries: Number of retry attempts on 429 or 5xx responses.

    Returns:
        dict: API response with enrichment results for every submitted indicator.
              Unknown indicators return classification 'unknown' — never omitted.

    Raises:
        ValueError:          If more than 500 indicators are submitted
        requests.HTTPError:  For unrecoverable 4xx errors
        RuntimeError:        If all retry attempts are exhausted

    Example:
        indicators = [
            {"type": "ip",     "value": "198.51.100.42"},
            {"type": "domain", "value": "malicious-c2.example.net"},
            {"type": "hash",   "value": "e3b0c44298fc1c149afb..."}
        ]
    """
    if len(indicators) > 500:
        raise ValueError("Bulk endpoint accepts a maximum of 500 indicators per request.")

    url     = f"{BASE_URL}/indicators/bulk"
    headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
    payload = {"indicators": indicators}

    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=payload, timeout=30)

            if response.status_code == 429:
                wait = int(response.headers.get("Retry-After", 60))
                print(f"Rate limited. Retrying in {wait} seconds...")
                time.sleep(wait)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.Timeout:
            wait = 2 ** attempt  # Exponential backoff: 1s, 2s, 4s
            print(f"Request timed out. Retrying in {wait}s... (attempt {attempt + 1}/{max_retries})")
            time.sleep(wait)

        except requests.exceptions.HTTPError as e:
            if e.response.status_code >= 500:
                wait = 2 ** attempt
                print(f"Server error {e.response.status_code}. Retrying in {wait}s...")
                time.sleep(wait)
                continue
            raise  # Do not retry 4xx errors other than 429

    raise RuntimeError(f"Request failed after {max_retries} attempts.")

SIEM Enrichment Workflow

The following five-step pipeline describes how to use this API to automatically enrich SIEM alerts with threat intelligence context during incident triage. Structured around NIST SP 800-61r3 incident response lifecycle guidance and MITRE ATT&CK v18 tactic-based detection conventions.

The 2026 Unit 42 Global Incident Response Report documents that attackers move from initial access to data exfiltration in under one hour in the fastest observed incidents — a 4x speed increase over prior years. Identity-based techniques drove initial access in 65% of investigated incidents. This pipeline is designed for the speed and triage discipline that threat environment demands.

Confidence Threshold Reference

Changelog

Citations & References

All technical content is sourced from publicly available research. No proprietary Palo Alto Networks data is reproduced.