Cypher API Reference

Last updated: March 2026

All queries go to https://graph.whisper.security and require an API key in the X-API-Key header. If you don't have a key yet, see Getting Started.

Query endpoint (POST)

Send a Cypher query as JSON.


Method	`POST`
URL	`/api/query`
Headers	`Content-Type: application/json`, `X-API-Key: $API_KEY`
Body	`{"query": "CYPHER_STRING", "parameters": {}}`

parameters is optional (defaults to {}).

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}
}

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%20%2B%201%20AS%20result"

Stats endpoint

Returns global node and edge counts.


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:

{
  "nodeCount": 3600000000,
  "edgeCount": 26000000000,
  "threatIntel": {
    "threatIntelLoaded": true,
    "hasTaxonomy": true,
    "feedSourceCount": 40,
    "categoryCount": 18,
    "totalListedInEdges": 3900000,
    "asnEnrichmentLoaded": true,
    "prefixBgpEnrichmentLoaded": true,
    "available": true
  },
  "timestamp": "2026-01-01T00:00:00.000000000Z"
}

Values are approximate and change with each data refresh.

Error responses

Bad queries come back as HTTP 400 with a structured error body:

{
  "message": "Unexpected token 'INVALID', expected MATCH/RETURN/WITH/UNWIND/CALL at position 0",
  "error": "CypherParseException",
  "timestamp": "2026-01-01T00:00:00.000000000Z"
}

Other error codes you may see:

Code	Error	Meaning
400	`CypherParseException`	Syntax error in your query
400	`CypherExecutionException`	Runtime error during execution
400	`CypherException`	Procedure argument problem (e.g., wrong number of args)
401	Unauthorized	Missing or invalid API key
408	`QueryTimeout`	Query ran too long. Response includes `timeoutMs`.
429	`QuotaExceeded`	You hit your plan's rate limit. Response includes `resetAt`.
502	`ExternalApiError`	An upstream service returned an error
503	`ExternalApiUnavailable`	Threat intel backend is temporarily down. Response includes `retryAfter`.