Cypher API Reference
HTTP endpoints for querying WhisperGraph — POST, GET, stats, threat intel status, infrastructure status, and error handling.
Cypher API Reference Documentation
All queries go to https://graph.whisper.security. Authenticate with an API key -- see Getting Started if you don't have one yet. Anonymous access (no key) is available with reduced limits.
Query endpoint (POST)
The primary query endpoint. Send a Cypher query as JSON.
| Method | POST |
| URL | /api/query |
| Headers | Content-Type: application/json, X-API-Key: $API_KEY |
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Cypher query |
parameters | object | No | Named parameters for parameterized queries |
timeout | long | No | Timeout override in milliseconds |
curl -s -X POST $BASE/api/query \
-H "Content-Type: application/json" \
-H "X-API-Key: $API_KEY" \
-d '{"query": "MATCH (n:ASN) RETURN n.name LIMIT 3"}'
Response:
{
"columns": ["n.name"],
"rows": [{"n.name": "AS1"}, {"n.name": "AS10"}, {"n.name": "AS100"}],
"statistics": {"rowCount": 3, "executionTimeMs": 3}
}
Parameter substitution
Use $paramName in your query and pass values in the parameters object:
curl -s -X POST $BASE/api/query \
-H "Content-Type: application/json" \
-H "X-API-Key: $API_KEY" \
-d '{"query": "MATCH (h:HOSTNAME {name: $host}) RETURN h.name", "parameters": {"host": "www.google.com"}}'
Query endpoint (GET)
For quick queries and browser testing -- pass the Cypher string as a query parameter.
| Method | GET |
| URL | /api/query?q=CYPHER_STRING |
| Headers | X-API-Key: $API_KEY |
curl -s -H "X-API-Key: $API_KEY" \
"$BASE/api/query?q=RETURN%201%20AS%20x"
Use POST for queries that contain special characters or are longer than a few hundred characters.
Stats endpoint
Returns aggregate graph statistics with physical, virtual, and total breakdowns for node and edge counts, plus threat intelligence status. Results are cached for 5 minutes.
| Method | GET |
| URL | /api/query/stats |
| Headers | X-API-Key: $API_KEY |
curl -s -H "X-API-Key: $API_KEY" $BASE/api/query/stats
Response:
{
"physical": {
"nodeCount": 3675848818,
"edgeCount": 30853203522
},
"virtual": {
"nodeCount": 3681675514,
"edgeCount": 7976807632
},
"total": {
"nodeCount": 7357524332,
"edgeCount": 38830011154
},
"objectCount": 46187535486,
"threatIntel": {
"threatIntelLoaded": true,
"hasTaxonomy": true,
"feedSourceCount": 40,
"categoryCount": 18,
"available": true
},
"timestamp": "2026-04-03T00:58:04.101459496Z"
}
Physical counts are nodes and edges stored on disk. Virtual counts are computed at query time from live infrastructure and threat intelligence data. The objectCount field is the sum of all nodes and edges.
Threat intelligence status
Returns details about the loaded threat intelligence layer.
| Method | GET |
| URL | /api/graph/threat-intel/status |
{
"hasTaxonomy": true,
"feedSourceCount": 40,
"categoryCount": 18,
"totalEdges": 5347784,
"ipCount": 2381780,
"domainCount": 2078279
}
Infrastructure status
Returns the state of the live infrastructure layer (BGP, RIR allocations, peering).
| Method | GET |
| URL | /api/graph/infrastructure/status |
{
"refreshInProgress": false,
"ready": true,
"asnCount": 116128,
"registeredPrefixCount": 324636,
"announcedPrefixCount": 1383546,
"peeringEdgeCount": 458853
}
Error responses
Error responses follow RFC 7807 problem detail format:
{
"type": "https://whisper.security/errors/query-depth-exceeded",
"title": "Query Depth Exceeded",
"status": 400,
"detail": "Query depth 3 exceeds maximum allowed depth of 2. Reduce traversal hops or upgrade your plan for deeper queries.",
"actualDepth": 3,
"maxAllowedDepth": 2
}
| Code | Condition | What to do |
|---|---|---|
| 400 | Invalid Cypher syntax | Check your query for typos or unsupported syntax |
| 400 | Query depth exceeds plan limit | Reduce traversal hops or upgrade your plan |
| 401 | Invalid API key | Verify your API key is correct |
| 408 | Query timeout | Add LIMIT, narrow the search, or simplify the pattern |
| 429 | Rate limit exceeded | Wait and retry, or upgrade your plan |
| 500 | Server error | Retry the request; if persistent, contact support |
| 502 | Upstream service error | An upstream service returned an error |
| 503 | External service unavailable | Infrastructure data source temporarily unreachable |
| 504 | Gateway timeout | Query took too long; simplify or add LIMIT |