AI Security Threat Board — API

Overview

• Base path /api/v1. All bodies are JSON (camelCase); timestamps are ISO-8601 UTC with a Z suffix.
• Caching: list endpoints, the docs page and the feed are cached at the edge and in the browser for five minutes (Cache-Control: public, max-age=300, s-maxage=300). The cache key is the route plus its validated parameters, so unrecognised parameters are ignored and do not produce a separate cache entry, and parameters that mean the same thing (limit=5 and limit=05, kev_first=1 and kev_first=true, the same instant written in two time zones) share one. /api/v1/status is cached for 60 seconds. The admin trigger is never cached.
• Conditional requests: every cached response carries a weak ETag derived from the data it reflects, not from the bytes. Send it back as If-None-Match and an unchanged resource answers 304 with no body — worth doing if you poll /rss.xml. The tag is weak because generatedAt is not part of it, so it stays valid across cache generations while the underlying data is unchanged.
• CORS: GET, HEAD and OPTIONS from any origin.
• Trust: every text field (titles, summaries, abstracts) is plain text derived from third-party feeds — escape it before rendering it as HTML. Links are always absolute http(s) URLs.
• Sources: CISA KEV and NVD (CVE API 2.0, keyword-filtered to AI/ML software) fill Active Threats — one row per CVE, shared by both sources; arXiv and Hugging Face Daily Papers fill Research; the RSS/Atom feeds in sources.json fill Incidents & Advisories.
• Board rows for withdrawn CVEs (badge REJECTED) are hidden everywhere unless a column route is asked for them.

Endpoints

GET /api/v1/latest

The board view: the newest items of each column. Threats are ordered with the CVEs CISA lists as actively exploited (badge KEV) first, newest first, followed by the remaining CVEs newest first — limit and days apply to the whole list, so a busy CNA day never hides an exploited vulnerability. Research is limited to items that finished LLM triage with a relevance at or above the board threshold (minRelevance in the response; 7 by default).

{ "generatedAt": "…", "lastUpdated": "…" | null, "minRelevance": 7,
  "columns": { "threats": [Item], "research": [Item], "incidents": [Item] } }

GET /api/v1/{column}

One column: threats, research or incidents. Unknown columns are a 404.

{ "column": "research", "generatedAt": "…", "lastUpdated": "…" | null,
  "count": 12, "minRelevance": 0 | n | null, "items": [Item] }

Board versus API relevance. The board (and /latest) shows research at or above the threshold only. The column route defaults to min_score=0 so the whole scored history is available, including pending items; pass min_score=7 to reproduce the board's selection.

Offline evaluation. GET /api/v1/research?min_score=0&include=abstract&limit=500&days=90 returns every scored abstract of the last quarter with the model and prompt version that scored it; worker/scripts/export-scored.sh in the repository turns that into JSON Lines.

GET /api/v1/status

Operational status: the last run per source and row counts. runs lists the newest run of every ingestion module plus the newest triage pass (source: "triage", triaged = items scored). lastUpdated is the finish time of the newest run that stored data — an ingestion run with status ok or partial (an error run stored nothing), or a triage pass that scored at least one item; it is the same value the board footer shows. counts.pendingTriage is the number of research items the next triage pass will pick up: pending ones plus failed ones still under the retry cap. Cached for 60 seconds.

{ "generatedAt": "…", "lastUpdated": "…" | null,
  "runs": [{ "source": "arxiv", "startedAt": "…", "finishedAt": "…" | null,
             "status": "ok" | "partial" | "error", "fetched": 3, "inserted": 1, "updated": 0, "triaged": 0, "error": null }],
  "counts": { "threats": 0, "research": 0, "incidents": 0, "pendingTriage": 0 } }

GET /api/v1/digest/latest

The newest weekly digest — a short Markdown analysis (≤ 400 words) of the last seven days' threats, research and incidents, written by the configured digest model every Monday — or a 404 while none has been written yet. The digest only ever discusses items that are on the board; it is skipped (and the board unaffected) when no digest provider is configured. Cached for five minutes.

{ "generatedAt": "…",
  "digest": { "id": 1, "periodStart": "…", "periodEnd": "…", "model": "…", "promptVersion": "…", "content": "# …", "createdAt": "…" } }

GET /rss.xml

RSS 2.0, the newest 50 items across all columns together with every CVE CISA added to KEV in the last 30 days, capped at 50 and ordered by publication date (KEV items keep their real date and are kept in preference to older non-KEV items when the cap applies). Research appears only once triaged at or above the board threshold. Item titles are prefixed with the column ([Threat], [Research], [Advisory], [Incident], [News]); a threat listed in CISA KEV is prefixed [KEV] instead; <category> carries the column, every badge and, for research, the triage tags; <guid> is the stable item id (not a permalink), with :kev appended once the CVE is in KEV so the addition surfaces once as a new item; the description is the one-line summary followed by the source and, where applicable, the relevance score or CVSS score and severity. Cached for five minutes; Content-Type: application/rss+xml.

POST /api/v1/admin/run/{source}

Runs an ingestion module synchronously and returns its outcome — for populating the board after a deploy or re-running a source without waiting for its cron. source is one of kev, nvd, arxiv, hf, rss, triage, digest or all (every source, then triage). Every source run ends with a triage pass over pending research.

• Requires Authorization: Bearer <ADMIN_TOKEN>. The token is a deployment secret; the route answers 404 when no token is configured and 401 for a missing or wrong one.
• ?triage_limit= (integer 1–200) caps the triage pass for this run.
• Responses carry Cache-Control: no-store. GET on this path is a 405.
• The triage result: status: "error" with an error starting provider failing means the model provider was not serving (the circuit breaker stopped the pass) and nothing was scored; partial means some items failed and the rest were scored; the notes carry the counts.

{ "generatedAt": "…", "requested": "arxiv",
  "results": [{ "source": "arxiv", "status": "ok" | "partial" | "error", "fetched": 3, "matched": 3, "inserted": 1, "updated": 0,
                "triaged": 0, "durationMs": 812, "error": null, "notes": [] },
              { "source": "triage", … }] }

Item shape

With include=abstract: abstract (plain text, ≤ 5000 chars), triageModel, promptVersion and triagedAt (all nullable).

Errors

Every non-2xx response is { "error": { "code": "…", "message": "…" } } with a stable code: bad_request (an invalid query parameter — the message names the parameter, never its value), unauthorized, not_found, method_not_allowed (with an Allow header), rate_limited (too many failed admin authentications from one address) and internal_error. Error responses are not cached.