REST API Reference¶

Base URL: http://localhost:7540

All request and response bodies are JSON. All endpoints return Content-Type: application/json.

Health¶

GET /health¶

Returns server health and runtime information.

Response 200:

{
  "status": "ok",
  "go_version": "go1.25.5",
  "goroutines": 5,
  "memory": {
    "alloc_mb": 2,
    "total_alloc_mb": 3,
    "sys_mb": 12
  }
}

Vertices¶

GET /api/v1/vertices¶

List all vertices. Optionally filter by type.

Query Parameters:

Response 200:

[
  {
    "id": "a1b2c3...",
    "type": "Person",
    "labels": ["suspect"],
    "properties": {"name": "Alice", "age": 30},
    "created_at": "2026-03-05T12:00:00Z",
    "updated_at": "2026-03-05T12:00:00Z"
  }
]

POST /api/v1/vertices¶

Create a new vertex.

Request Body:

{
  "type": "Person",
  "labels": ["suspect"],
  "properties": {"name": "Alice", "age": 30}
}

Response 201: Returns the created vertex with a generated ID.

GET /api/v1/vertices/:id¶

Get a vertex by ID.

Response 200: Returns the vertex object.

Response 404: {"error": "vertex not found"}

PUT /api/v1/vertices/:id¶

Update a vertex. Merges properties with existing values.

Request Body:

{
  "type": "Person",
  "labels": ["suspect", "witness"],
  "properties": {"age": 31}
}

All fields are optional. Only provided fields are updated. Properties are merged, not replaced.

Response 200: Returns the updated vertex.

DELETE /api/v1/vertices/:id¶

Delete a vertex and all its connected edges.

Response 204: No content.

GET /api/v1/vertices/:id/edges¶

Get all edges connected to a vertex.

Query Parameters:

Response 200: Returns an array of edge objects.

GET /api/v1/vertices/:id/neighbors¶

Get all neighboring vertices.

Query Parameters:

Response 200: Returns an array of vertex objects.

Edges¶

GET /api/v1/edges¶

List all edges. Optionally filter by type.

Query Parameters:

POST /api/v1/edges¶

Create a new edge.

Request Body:

{
  "source_id": "a1b2c3...",
  "target_id": "d4e5f6...",
  "type": "knows",
  "properties": {"since": "2020"},
  "directed": true,
  "weight": 1.0
}

directed defaults to true. weight defaults to 1.0.

Both source_id and target_id must refer to existing vertices.

Response 201: Returns the created edge.

Response 400: {"error": "vertex not found"} if source or target does not exist.

GET /api/v1/edges/:id¶

Get an edge by ID.

PUT /api/v1/edges/:id¶

Update edge properties and/or weight.

Request Body:

{
  "properties": {"since": "2019"},
  "weight": 2.5
}

DELETE /api/v1/edges/:id¶

Delete an edge.

Response 204: No content.

Graph Operations¶

GET /api/v1/graph/stats¶

Get graph statistics.

Response 200:

{
  "vertex_count": 150,
  "edge_count": 420,
  "storage_type": "disk",
  "size_bytes": 65536
}

POST /api/v1/graph/flush¶

Force a flush of in-memory data to disk.

Response 200: {"status": "flushed"}

Query¶

POST /api/v1/query¶

Execute a query against the graph.

Request Body:

{
  "type": "vertices",
  "vertex_type": "Person",
  "labels": ["suspect"],
  "properties": {"city": "Berlin"},
  "limit": 10,
  "offset": 0
}

Response 200:

{
  "vertices": [...],
  "edges": [...],
  "count": 5
}

Traversal¶

GET /api/v1/traversal/bfs/:id¶

Breadth-first traversal from a starting vertex.

Query Parameters:

Response 200: Array of vertices in BFS order.

GET /api/v1/traversal/dfs/:id¶

Depth-first traversal from a starting vertex. Same parameters as BFS.

GET /api/v1/traversal/shortest-path/:from/:to¶

Find the shortest path between two vertices.

Query Parameters:

Response 200:

{
  "vertices": [...],
  "edges": [...]
}

Response 404: If no path exists.

GET /api/v1/traversal/all-paths/:from/:to¶

Find all paths between two vertices.

Query Parameters:

Response 200: Array of path objects, each containing vertices and edges.