Agent Integration Guide

REST API

Works with any language, any platform, any agent framework. Get your API key, make your first call, scale from there.

Time: ~3 minutes
Works with: Any language or platform
Auth: Bearer token (API key)

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
Create an entity

Create a node in your knowledge graph — the first write to ThreatRecall memory.

cURL 
curl -X POST https://app.threatrecall.ai/api/graph/nodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -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. The response includes the node 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

Natural language recall or structured graph traversal.

Natural language recall:

GET /api/recall/search 
curl "https://app.threatrecall.ai/api/recall/search?query=APT-41%20CVEs" \
  -H "Authorization: Bearer YOUR_API_KEY"
Returns matching actors, CVEs, TTPs, and IOCs ranked by relevance and confidence.

Graph traversal:

GET /api/graph/nodes/:id 
curl https://app.threatrecall.ai/api/graph/nodes/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -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 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -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/search?query=... Natural language search across your knowledge graph.
POST /api/graph/nodes Create a new entity (actor, CVE, IOC, TTP, etc.).
GET /api/graph/nodes/:id Get a specific node by ID.
GET /api/graph Get the full graph or a subgraph.
GET /api/graph/nodes/: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/logs Query your audit log (write-once, immutable).

Request/response examples

Recall — search for CVEs

Request 
curl "https://app.threatrecall.ai/api/recall/search?query=ransomware%20CVE" \
  -H "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 all required fields are present.
Problem: Empty results from recall
Fix: Your query may not match existing data. Try a simpler query like "malware". If that returns nothing, add some entities to your workspace first.