Documentation

REST / Cypher API

Connection — REST / Cypher API

The simplest way to interact with JetGraph from any language. Send a JSON body with a query (Cypher string) and optional parameters to POST /cypher.

Base URL

http://localhost:8080

Request Format

Field	Type	Description
`query`	string	A Cypher query string
`parameters`	object	Named parameters referenced as `$name` in the query

Response Format

Successful responses return a JSON object with columns and rows:

{"columns": ["id", "label"], "rows": [["user-001", "USER"]]}

Example Requests

bash — create a node

curl -sS -X POST http://localhost:8080/cypher \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "CREATE (u:USER {external_id: $id, email: $email}) RETURN u.external_id AS id",
    "parameters": {"id": "user-001", "email": "alice@example.com"}
  }'
# → {"columns":["id"],"rows":[["user-001"]]}

bash — match nodes

curl -sS -X POST http://localhost:8080/cypher \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "MATCH (u:USER) RETURN u.external_id AS id LIMIT 10",
    "parameters": {}
  }'

bash — create a relationship

curl -sS -X POST http://localhost:8080/cypher \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "MATCH (u:USER {external_id: $uid}), (m:MERCHANT {external_id: $mid}) CREATE (u)-[:TRANSACTS_AT]->(m) RETURN true AS created",
    "parameters": {"uid": "user-001", "mid": "merchant-42"}
  }'

Additional Endpoints

Method	Path	Description
`GET`	`/health`	Returns JSON with `ready=true`; 503 while loading snapshot
`GET`	`/metrics`	Prometheus text metrics — ingest rate, query counters, memory pressure, RCU retries

Error Responses

On error, JetGraph returns a non-2xx HTTP status with a JSON error body:

{"error": "Schema not finalized. Call db.finalizeSchema() before writing data."}

HTTP Status	Meaning
`200 OK`	Query executed successfully
`400 Bad Request`	Malformed query or invalid parameters
`409 Conflict`	Schema conflict or duplicate node type
`500 Internal Server Error`	Unexpected engine error — check logs
`503 Service Unavailable`	Engine still loading snapshot at startup — retry after a moment