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": "[email protected]" }

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);

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.