GET /v1/projects/{id}/alerts

Alerts are created automatically when a CVE matches an item in a project’s stack. Each alert includes the associated CVE metadata (CVSS score, severity, KEV, PoC).

List Project Alerts

GET /api/v1/projects/{project_id}/alerts
Authorization: Bearer twa_your_key_here

Path Parameters

Parameter	Type	Description
project_id	UUID	Project identifier

Query Parameters

Parameter	Type	Default	Description
unread_only	boolean	false	If true, returns only unread alerts
severity	string	—	Filter by severity (comma-separated). Values: CRITICAL, HIGH, MEDIUM, LOW
since	datetime (ISO 8601)	—	Returns only alerts triggered after this date
page	integer ≥ 1	1	Page number
limit	integer 1–200	50	Alerts per page

Response 200 OK

{
  "items": [
    {
      "id": "018e9999-0000-7000-8000-000000000030",
      "cve_id": "CVE-2024-11477",
      "triggered_at": "2024-11-05T14:32:00Z",
      "is_read": false,
      "severity": "CRITICAL",
      "description": "7-Zip contains a heap-based buffer overflow vulnerability...",
      "vendor": "7-zip",
      "product": "7-zip",
      "cvss_score": 7.8,
      "is_kev": false,
      "has_poc": true
    },
    {
      "id": "018e9999-0000-7000-8000-000000000031",
      "cve_id": "CVE-2024-38816",
      "triggered_at": "2024-09-13T08:00:00Z",
      "is_read": true,
      "severity": "HIGH",
      "description": "Applications serving static resources through the functional web...",
      "vendor": "vmware",
      "product": "spring_framework",
      "cvss_score": 7.5,
      "is_kev": false,
      "has_poc": false
    }
  ],
  "total": 42,
  "unread_count": 7
}

Fields — Envelope

Field	Type	Description
items	array	Alerts on the current page
total	integer	Total alerts matching the active filters
unread_count	integer	Total unread alerts in this project (independent of filters)

Fields — Alert

Field	Type	Description
id	string (UUID)	Alert identifier
cve_id	string	CVE identifier (e.g. CVE-2024-11477)
triggered_at	string (ISO 8601)	Trigger timestamp
is_read	boolean	true if the alert was marked as read in the app
severity	string	CVE severity: CRITICAL, HIGH, MEDIUM, LOW, NONE, UNKNOWN
description	string | null	English description of the CVE
vendor	string | null	Identified primary vendor
product	string | null	Identified primary product
cvss_score	float | null	CVSS score (0.0 – 10.0)
is_kev	boolean	true if listed in the CISA KEV catalog
has_poc	boolean	true if at least one public PoC is known (nomi-sec/PoC-in-GitHub)

---

Get a Single Alert

GET /api/v1/projects/{project_id}/alerts/{alert_id}
Authorization: Bearer twa_your_key_here

Path Parameters

Parameter	Type	Description
project_id	UUID	Project identifier
alert_id	UUID	Alert identifier

Response 200 OK

Same structure as a list item.

Errors

Code	Detail	Cause
404	Projet introuvable	project_id does not exist
403	Accès refusé à ce projet	Project not accessible
404	Alerte introuvable	alert_id does not exist or does not belong to this project

---

Examples

Unread critical alerts from the last 30 days

SINCE=$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
  || date -u -v-30d +%Y-%m-%dT%H:%M:%SZ)

curl -s \
  -H "Authorization: Bearer twa_your_key_here" \
  "https://app.techwatchalert.com/api/v1/projects/${PROJECT_ID}/alerts?severity=CRITICAL,HIGH&unread_only=true&since=${SINCE}&limit=100" \
  | jq '.items[] | {cve: .cve_id, score: .cvss_score, kev: .is_kev, poc: .has_poc}'

CI/CD script — fail build on critical CVE with PoC

#!/bin/bash
set -euo pipefail

PROJECT_ID="${TWA_PROJECT_ID}"
API_KEY="${TWA_API_KEY}"
BASE="https://app.techwatchalert.com/api/v1"

CRITICAL_POC=$(curl -sf \
  -H "Authorization: Bearer ${API_KEY}" \
  "${BASE}/projects/${PROJECT_ID}/alerts?severity=CRITICAL&unread_only=true&limit=200" \
  | jq '[.items[] | select(.has_poc == true)] | length')

if [ "$CRITICAL_POC" -gt 0 ]; then
  echo "ERROR: ${CRITICAL_POC} critical CVE(s) with PoC unaddressed."
  exit 1
fi

echo "OK — no critical CVEs with PoC."

Python — export alerts to CSV

import csv, httpx
from datetime import datetime, timedelta, timezone

BASE = "https://app.techwatchalert.com/api/v1"
headers = {"Authorization": "Bearer twa_your_key_here"}
project_id = "018e1234-abcd-7000-8000-000000000010"

since = (datetime.now(timezone.utc) - timedelta(days=7)).isoformat()
page, all_alerts = 1, []

while True:
    r = httpx.get(
        f"{BASE}/projects/{project_id}/alerts",
        headers=headers,
        params={"since": since, "limit": 200, "page": page},
    ).json()
    all_alerts.extend(r["items"])
    if len(all_alerts) >= r["total"]:
        break
    page += 1

with open("alerts.csv", "w", newline="") as f:
    w = csv.DictWriter(f, fieldnames=["cve_id", "severity", "cvss_score", "is_kev", "has_poc", "triggered_at"])
    w.writeheader()
    w.writerows(all_alerts)

print(f"{len(all_alerts)} alerts exported.")