Developer API

OpenTrojan exposes a versioned REST API from a Cloudflare Worker. All /api/v1/* responses use a uniform envelope: { data, version, requestId }.

Quick Start

  1. Register an identity: POST /api/v1/identity/register (email or anonymous)
  2. Create an API key: POST /api/v1/keys → keep the returned apiKey (shown once)
  3. Serve authenticated calls by sending header: x-api-key: <your key>
  4. Explore: GET /api/v1/search?q=CVE-2021-44228

API Reference

GET /health

Service health & bindings.

Request

GET /health

Response

{ "ok": true, "env": "prod", "dbBound": true, "r2Bound": true }

GET /api/v1/entities/:id/graph

Entity knowledge graph (entity/relations/neighbors/evidence).

Request

GET /api/v1/entities/CVE-2021-44228/graph

Response

{ "entity": {…}, "relations": […], "neighbors": {…}, "evidence": {…} }

POST /api/ai/ask

Citation-based security Q&A.

Request

POST /api/ai/ask  { "question": "What is CVE-2021-44228?", "locale": "en" }

Response

{ "answer": "…", "sources": […], "references": […], "meta": {…} }

POST /api/ai/report

Security brief generator.

Request

POST /api/ai/report  { "topic": "CVE-2021-44228" }

Response

{ "topic": "…", "intent": "cve_analysis", "brief": { "summary": "…", "risk": "critical", "recommendations": […] } }

POST /api/tools/:tool

Defensive security tool.

Request

POST /api/tools/hash  { "input": "<64-hex>" }

Response

{ "tool": "hash", "risk": "unknown", "score": 1, "findings": […], "references": […] }

GET /api/v1/search?q=

Machine-readable security intelligence search.

Request

GET /api/v1/search?q=log4shell&limit=5

Response

{ "data": { "query": "log4shell", "hits": […], "entities": […] }, "version": "1.0.0", "requestId": "req_…" }

GET /api/v1/cve/latest

Latest published CVEs (machine feed).

Request

GET /api/v1/cve/latest?limit=10

Response

{ "data": { "items": [{ "id": "CVE-…", "published": "…" }], "count": 10 }, "version": "1.0.0", "requestId": "req_…" }

GET /api/v1/kev/latest

Latest CISA KEV additions (machine feed).

Request

GET /api/v1/kev/latest?limit=10

Response

{ "data": { "items": [{ "id": "CVE-…", "dateAdded": "…" }], "count": 10 }, "version": "1.0.0", "requestId": "req_…" }

POST /api/v1/keys

Create an API key (plaintext returned once).

Request

POST /api/v1/keys  { "label": "ci" }

Response

{ "data": { "apiKey": "ot_…", "keyHash": "sha256…" }, "version": "1.0.0", "requestId": "req_…" }

POST /api/v1/identity/register

Register an anonymous or email identity.

Request

POST /api/v1/identity/register  { "email": "user@example.com" }

Response

{ "data": { "identity": { "id": 1, "privacyFlag": true } }, "version": "1.0.0", "requestId": "req_…" }

Examples

curl — search

curl "https://api.opentrojan.com/api/v1/search?q=CVE-2021-44228&limit=3" \
  -H "x-api-key: ot_…"

curl — latest CVEs

curl "https://api.opentrojan.com/api/v1/cve/latest?limit=5"

Node/TypeScript (SDK-like)

const res = await fetch(BASE + '/api/v1/search?q=' + q, {
  headers: { 'x-api-key': process.env.OPEN_TROJAN_KEY }
});
const { data } = await res.json();
console.log(data.hits);

API Catalog

Core capability endpoints with curl and (Python / TypeScript) examples.

Security Search — GET /api/v1/search?q=:query

Machine-readable security intelligence search across CVEs, entities and documents.

curl

curl "https://api.opentrojan.com/api/v1/search?q=log4shell&limit=5" \
  -H "x-api-key: ot_…"

python

import requests
r = requests.get("https://api.opentrojan.com/api/v1/search",
    params={"q": "log4shell", "limit": 5},
    headers={"x-api-key": "ot_…"})
data = r.json()["data"]
print(data["hits"])

typescript

const res = await fetch(
  BASE + '/api/v1/search?q=log4shell&limit=5',
  { headers: { 'x-api-key': process.env.OPEN_TROJAN_KEY } }
);
const { data } = await res.json();
console.log(data.hits);

CVE — GET /api/v1/cve/:id

Fetch a single CVE record with severity, CVSS, KEV status and references.

curl

curl "https://api.opentrojan.com/api/v1/cve/CVE-2021-44228" \
  -H "x-api-key: ot_…"

python

import requests
r = requests.get("https://api.opentrojan.com/api/v1/cve/CVE-2021-44228",
    headers={"x-api-key": "ot_…"})
print(r.json()["data"])

typescript

const res = await fetch(
  BASE + '/api/v1/cve/CVE-2021-44228',
  { headers: { 'x-api-key': process.env.OPEN_TROJAN_KEY } }
);
const { data } = await res.json();
console.log(data);

Entity Graph — GET /api/v1/entities/:id/graph

Entity knowledge graph: entity, relations, neighbors and evidence chains.

curl

curl "https://api.opentrojan.com/api/v1/entities/CVE-2021-44228/graph" \
  -H "x-api-key: ot_…"

python

import requests
r = requests.get("https://api.opentrojan.com/api/v1/entities/CVE-2021-44228/graph",
    headers={"x-api-key": "ot_…"})
graph = r.json()["data"]
print(graph["neighbors"])

typescript

const res = await fetch(
  BASE + '/api/v1/entities/CVE-2021-44228/graph',
  { headers: { 'x-api-key': process.env.OPEN_TROJAN_KEY } }
);
const { data } = await res.json();
console.log(data.relations);

AI Report — POST /api/ai/report

Generate a security brief with summary, risk and recommendations for analyst review.

curl

curl -X POST "https://api.opentrojan.com/api/ai/report" \
  -H "x-api-key: ot_…" -H "Content-Type: application/json" \
  -d '{ "topic": "CVE-2021-44228" }'

python

import requests
r = requests.post("https://api.opentrojan.com/api/ai/report",
    json={"topic": "CVE-2021-44228"},
    headers={"x-api-key": "ot_…", "Content-Type": "application/json"})
print(r.json()["brief"]["recommendations"])

typescript

const res = await fetch(BASE + '/api/ai/report', {
  method: 'POST',
  headers: { 'x-api-key': process.env.OPEN_TROJAN_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ topic: 'CVE-2021-44228' }),
});
const { brief } = await res.json();
console.log(brief.recommendations);

Intelligence Feed — GET /api/v1/feed?interests=:comma-list

Personalized feed: CVE updates, KEV additions, threat activity and advisories, each with a match reason.

curl

curl "https://api.opentrojan.com/api/v1/feed?interests=log4j,cloud,ransomware" \
  -H "x-api-key: ot_…"

python

import requests
r = requests.get("https://api.opentrojan.com/api/v1/feed",
    params={"interests": "log4j,cloud,ransomware"},
    headers={"x-api-key": "ot_…"})
for item in r.json()["data"]["items"]:
    print(item["title"], "—", item["matchReason"])

typescript

const res = await fetch(
  BASE + '/api/v1/feed?interests=log4j,cloud,ransomware',
  { headers: { 'x-api-key': process.env.OPEN_TROJAN_KEY } }
);
const { data } = await res.json();
data.items.forEach(i => console.log(i.title, '—', i.matchReason));

MCP Registry

Model Context Protocol tools available to AI agents; each maps to the catalog above.

  • search_security — Search security intelligence by keyword; returns hits and related entities.
  • get_cve — Fetch a single CVE with severity, CVSS, KEV status and references.
  • get_entity_graph — Traverse entity relationships and evidence chains for an ID.
  • generate_report — Produce a reviewable security brief with risk and recommendations.

Playground

Copy-paste starter requests to explore the API live.

GET /api/v1/search?q=CVE-2021-44228&limit=3

→ 200 — { data: { query, hits, entities }, version }

GET /api/v1/cve/latest?limit=5

→ 200 — { data: { items, count }, version }

POST /api/v1/keys

{ "label": "playground", "scope": "read", "quota": 100 }

→ 200 — { data: { apiKey, keyHash, scope, quota } }

POST /api/ai/soc

{ "topic": "CVE-2021-44228" }

→ 200 — { topic, risk, summary, fixRecommendation, priorityReasoning }

POST /api/v1/rules/evaluate

{ "event": "kev_added", "entity": { "id": "CVE-1", "severity": "critical" } }

→ 200 — { data: { matches } }

Rate Limits

Requests are limited per IP via sliding window (default 120 req/min). Responses include X-RateLimit-Limit / Remaining / Reset; excess returns 429.

Errors

{ "code": "bad_request|not_found|rate_limited", "message": "…", "requestId": "req_…", "version": "1.0.0" }

SDK Roadmap

  • REST client planned — Typed fetch client for all /api/v1 endpoints + auth headers.
  • MCP tool bindings planned — First-class bindings for search_security / get_cve / get_entity_graph / generate_report.
  • Webhook delivery planned — Subscription to watchlist notifications via webhook.
  • OAuth / billing later — Explicitly out of current scope; traffic governed by rate limits.