OpenTrojan Intelligence Infrastructure
Search intelligence, CVEs, threats… Search
Ask AI Analyst API
English中文
Enter Portal
Developersv1–v22 · 100+ MCP tools

Developer API

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

Try the playground Browse MCP tools API v3 reference

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
  5. Or use the JS SDK: `pnpm add @opentrojan/sdk-js` → `new OpenTrojanClient()` → `client.search("log4j")`（见 sdk-js/quickstart.md）

First 5 minutes (Phase 45G)

  1. Get an API key — no signup friction: use the public endpoints (/api/v1/search, /api/v1/cve/latest) or request a key for authenticated v1+ access (see API reference).
  2. Call the search API — try it below or in the playground.
  3. Query an intelligence entity — CVE-2021-44228, a campaign or a threat actor.
  4. Build your integration — consume the uniform envelope (data / version / requestId), handle 4xx/5xx, respect rate limits (see Error Handling & Rate Limits).

Developer Quick Start

Copy-paste examples — search intelligence, fetch an entity, query daily briefs, and integrate via MCP. SDK: @opentrojan/sdk-js.

Search intelligence JavaScript (sdk-js)

import { OpenTrojanClient } from '@opentrojan/sdk-js';

const client = new OpenTrojanClient({ baseUrl: 'https://api.opentrojan.com' });

// Search CVEs and entities
const results = await client.search('log4shell', 5);
console.log(results); // { data: { results: [...] } }

Search intelligence Python

from open_trojan import OpenTrojanClient

client = OpenTrojanClient(base_url="https://api.opentrojan.com")

results = client.search("log4shell", limit=5)
print(results)  # {"data": {"results": [...]}}

Get an entity + daily intelligence JavaScript (sdk-js)

const cve = await client.getEntity('CVE-2021-44228');   // entity detail
const daily = await client.intelligence();                     // daily brief

// MCP integration: use the same endpoint via MCP tools
// mcp add open-trojan -- /your/mcp/server.js  (registry exposes 100+ read-only tools)

Query intelligence without an SDK REST (curl)

# Search
curl "https://api.opentrojan.com/api/v1/search?q=log4j&limit=5"

# Daily intelligence brief
curl "https://api.opentrojan.com/api/v20/daily/intelligence"

# Reliability / quality operations (read-only)
curl "https://api.opentrojan.com/api/v1/reliability"
curl "https://api.opentrojan.com/api/v1/quality/ops"

Error Handling & Rate Limits

  • Envelope: Every response is { data | error, version, requestId }; use requestId for support.
  • Error codes: 400 bad_request · 401 unauthorized · 403 forbidden · 404 not_found · 429 too_many_requests · 5xx server_error.
  • Rate limits: Public endpoints are rate-limited per minute bucket; check Rate-Limit-Remaining header and back off on 429.
  • AI & review: AI responses always carry requiresReview:true and confidence/sources — never auto-publish.

JS SDK quickstart & runnable examples: packages/sdk-js/quickstart.md · packages/sdk-js/examples/

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

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 (sdk-js) done — Typed fetch client for /api/v1 endpoints + auth headers（@opentrojan/sdk-js，quickstart + examples 已提供）.
  • 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.
  • Python SDK (sdk-python) planned — Python examples/quickstart next（Phase 39F 记录为待办）.

Explore integrated tooling in the API Marketplace · Developer Ecosystem · MCP Tools