REST API Reference

Base URL

• Production: https://api.graphdb-labs.com (via edge-gateway)
• Local dev: http://localhost:8787 (via graphdb dev)

Authentication

In production, all requests require an API key:

Authorization: Bearer gdb_live_xxxxxxxx

In local dev (graphdb dev), include X-Tenant-Id header:

X-Tenant-Id: dev-tenant

Endpoints

Health

GET /health

Projects

POST   /v1/projects              # Create project
GET    /v1/projects              # List projects
GET    /v1/projects/{projectId}  # Get project

Graphs

POST   /v1/projects/{projectId}/graphs  # Create graph
GET    /v1/projects/{projectId}/graphs  # List graphs
GET    /v1/graphs/{graphId}             # Get graph
DELETE /v1/graphs/{graphId}             # Delete graph

Schema

POST   /v1/graphs/{graphId}/schema/node-types  # Create node type
GET    /v1/graphs/{graphId}/schema/node-types  # List node types
POST   /v1/graphs/{graphId}/schema/edge-types  # Create edge type
GET    /v1/graphs/{graphId}/schema/edge-types  # List edge types

Nodes

POST   /v1/graphs/{graphId}/nodes              # Create node
GET    /v1/graphs/{graphId}/nodes              # List nodes (?type=X&limit=100&offset=0)
GET    /v1/graphs/{graphId}/nodes/{nodeId}     # Get node
PUT    /v1/graphs/{graphId}/nodes/{nodeId}     # Update node properties
DELETE /v1/graphs/{graphId}/nodes/{nodeId}     # Delete node

Edges

POST   /v1/graphs/{graphId}/edges              # Create edge
GET    /v1/graphs/{graphId}/edges              # List edges (?nodeId=X&direction=both)
GET    /v1/graphs/{graphId}/edges/{edgeId}     # Get edge
DELETE /v1/graphs/{graphId}/edges/{edgeId}     # Delete edge

Traversal

POST   /v1/graphs/{graphId}/traverse           # BFS traversal

Agentic Query

POST   /v1/graphs/{graphId}/agentic-query      # Vector + graph hybrid query

Error format

All errors follow a consistent JSON format:

{
  "error": "validation_error",
  "details": {
    "fieldErrors": { "type": ["Required"] },
    "formErrors": []
  }
}

HTTP Status	Error code	Meaning
400	validation_error	Request body failed Zod validation
403	UNTRUSTED_REQUEST	Missing or invalid trust signature
404	graph_not_found	Graph ID not found for this tenant
404	node_not_found	Node ID not found in graph
500	internal_server_error	Unexpected server error