REST API — ThreatRecall Docs

What you'll need

✓ A ThreatRecall API key (from Settings → API Keys in your dashboard)
✓ Any HTTP client — curl, fetch, Python requests, etc.
✓ Your workspace URL: https://app.threatrecall.ai

Step-by-step setup

Step 1

Your first API call — create an entity

Start by creating a node in your knowledge graph. This is your agent's first memory write.

cURL

curl -X POST https://app.threatrecall.ai/api/nodes \n
  -H "Authorization: Bearer YOUR_API_KEY" \n
  -H "Content-Type: application/json" \n
  -d '{
    "type": "actor",
    "name": "APT-41",
    "aliases": ["BARIUM", "WICKED PANDORA"],
    "tags": ["china", "espionage", "financially-motivated"],
    "confidence": 0.95
  }'

A new actor node named APT-41 is created in your workspace. The response includes the node's ID — save it for the next step.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "actor",
  "name": "APT-41",
  "created_at": "2026-05-26T20:00:00.000Z",
  "confidence": 0.95
}

Step 2

Query the knowledge graph

Use the recall endpoint for natural language search, or the graph endpoint for structured traversal.

Natural language recall:

GET /api/recall

curl "https://app.threatrecall.ai/api/recall?query=APT-41%20CVEs" \n
  -H "Authorization: Bearer YOUR_API_KEY"

Returns matching actors, CVEs, TTPs, and IOCs ranked by relevance and confidence.

Graph traversal (get all edges from a node):

GET /api/graph/node/:id

curl https://app.threatrecall.ai/api/graph/node/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \n
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the node with all its outgoing relationships — actors linked to TTPs, CVEs, campaigns, IOCs.

Step 3

Add a relationship (edge)

Connect two nodes with a labeled relationship.

POST /api/graph/edges

curl -X POST https://app.threatrecall.ai/api/graph/edges \n
  -H "Authorization: Bearer YOUR_API_KEY" \n
  -H "Content-Type: application/json" \n
  -d '{
    "source_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "target_id": "cve-node-id-here",
    "relationship": "exploits",
    "confidence": 0.9
  }'

An edge is created linking APT-41 to the CVE. Your knowledge graph now shows the exploit relationship.

Full endpoint reference

Method	Endpoint	Description
GET	`/api/recall?query=...`	Natural language search across your knowledge graph.
POST	`/api/nodes`	Create a new entity (actor, CVE, IOC, TTP, etc.).
GET	`/api/nodes/:id`	Get a specific node by ID.
GET	`/api/graph`	Get the full graph or a subgraph.
GET	`/api/graph/node/:id`	Get a node with all its edges.
POST	`/api/graph/edges`	Create a relationship edge between two nodes.
POST	`/api/incidents`	Create an incident record.
POST	`/api/evidence`	Add an evidence record (STIX-compatible provenance).
GET	`/api/audit`	Query your audit log (write-once, immutable).

Request/response examples

Recall — search for CVEs

Request

GET /api/recall?query=ransomware%20CVE
Authorization: Bearer YOUR_API_KEY

Response

{
  "results": [
    {
      "id": "cve-2021-34527",
      "type": "cve",
      "name": "CVE-2021-34527 (PrintNightmare)",
      "score": 0.91,
      "matched_on": "name, description, tags"
    }
  ],
  "query": "ransomware CVE",
  "total": 1
}

Troubleshooting

Problem: 401 Unauthorized
Fix: Your API key is missing or incorrect. Copy it from Settings → API Keys in your dashboard exactly as shown — no extra spaces or newlines.

Problem: 400 Bad Request
Fix: Check the JSON body. Make sure the Content-Type: application/json header is set, and that all required fields are present. Run jsonlint or a similar tool to validate the payload.

Problem: Empty results from recall
Fix: Your query may not match existing data. Try a simpler or more generic query like "malware". If that returns nothing, add some entities to your workspace first.