Quickstart

Local development (graphdb dev)

Start the full graph engine stack locally — no cloud credentials required.

# 1. Initialize a new project
npx @graphdb-labs/cli init my-rag-project
cd my-rag-project

# 2. Start the local stack
npx @graphdb-labs/cli dev
# → http://localhost:8787 is now running
# → D1 local SQLite + Durable Object emulation + KV local store
# → X-Internal-Sig check bypassed (ENVIRONMENT=development)
# → Default tenant: dev-tenant

Create your first graph

# Create a project
curl -X POST http://localhost:8787/v1/projects \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{ "name": "My RAG Project", "slug": "my-rag-project" }'

# Create a graph
curl -X POST http://localhost:8787/v1/projects/{projectId}/graphs \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{ "name": "main", "environment": "production" }'

Define a schema

# Define a Document node type
curl -X POST http://localhost:8787/v1/graphs/{graphId}/schema/node-types \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{
    "typeName": "Document",
    "fieldDefs": [
      { "name": "title", "type": "string", "required": true },
      { "name": "source", "type": "string" }
    ]
  }'

# Define a Chunk node type
curl -X POST http://localhost:8787/v1/graphs/{graphId}/schema/node-types \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{
    "typeName": "Chunk",
    "fieldDefs": [
      { "name": "text", "type": "string", "required": true },
      { "name": "vector_id", "type": "string" }
    ]
  }'

# Define a HAS_CHUNK edge type
curl -X POST http://localhost:8787/v1/graphs/{graphId}/schema/edge-types \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{
    "typeName": "HAS_CHUNK",
    "fromType": "Document",
    "toType": "Chunk"
  }'

Create nodes and edges

# Create a Document node
curl -X POST http://localhost:8787/v1/graphs/{graphId}/nodes \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{
    "id": "doc_1",
    "type": "Document",
    "properties": { "title": "Refund Policy", "source": "handbook" }
  }'

# Create Chunk nodes
curl -X POST http://localhost:8787/v1/graphs/{graphId}/nodes \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{
    "id": "chunk_1",
    "type": "Chunk",
    "properties": { "text": "Refunds are processed within 7 days..." }
  }'

# Link them
curl -X POST http://localhost:8787/v1/graphs/{graphId}/edges \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{
    "fromNode": "doc_1",
    "toNode": "chunk_1",
    "type": "HAS_CHUNK"
  }'

Traverse the graph

curl -X POST http://localhost:8787/v1/graphs/{graphId}/traverse \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: dev-tenant" \
  -d '{
    "startNodeId": "doc_1",
    "maxDepth": 2,
    "edgeTypes": ["HAS_CHUNK"]
  }'

Deploy to production

Deploy through GitHub Actions on the product repos (core, edge-gateway, …).
Do not run local wrangler deploy. See Deployment.

# Optional: push local schema against a linked cloud project (when CLI supports it)
npx @graphdb-labs/cli link --project <project-id>
npx @graphdb-labs/cli push