Quick Start Guide

Get up and running with your KnowledgeFlowDB hosted database in under 5 minutes.

1. Connect Your Wallet

Visit db.knowledgedataflow.org and connect your wallet. Your wallet address is your identity — no accounts or passwords needed.

Authentication Options

There are two ways to authenticate:

• Simple: Pass your wallet address via the X-Wallet-Address header (shown in examples below)
• Production: Sign a challenge with your wallet to get a Bearer JWT token (valid 24h). See Wallet Auth for the full flow.

After connecting, you'll have:

• API Endpoint: https://api.knowledgedataflow.org
• Authentication: Your wallet address via X-Wallet-Address header

2. Test Your Connection

Use curl to verify your database is accessible:

curl -H "X-Wallet-Address: YOUR_WALLET_ADDRESS" \
     -H "Content-Type: application/json" \
     -d '{"query": "MATCH (n) RETURN count(n)"}' \
     https://api.knowledgedataflow.org/api/v1/query

Expected response:

{
  "data": [{"count(n)": 0}],
  "stats": {
    "execution_time_ms": 1.23,
    "nodes_scanned": 0,
    "edges_traversed": 0,
    "results_returned": 1
  }
}

3. Create Your First Node

Write your first data to the database:

curl -X POST https://api.knowledgedataflow.org/api/v1/write \
  -H "X-Wallet-Address: YOUR_WALLET_ADDRESS" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [{
      "operation": "create_node",
      "label": "Person",
      "properties": {
        "name": {"String": "Alice"},
        "age": {"Integer": 30}
      }
    }]
  }'

Expected response:

{
  "operations_executed": 1,
  "execution_time_ms": 2.45,
  "affected_ids": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"]
}

4. Query Your Data

Now query the node you just created:

curl -H "X-Wallet-Address: YOUR_WALLET_ADDRESS" \
     -H "Content-Type: application/json" \
     -d '{"query": "MATCH (p:Person) RETURN p.name AS name, p.age AS age"}' \
     https://api.knowledgedataflow.org/api/v1/query

Expected response:

{
  "data": [
    {
      "name": {"String": "Alice"},
      "age": {"Integer": 30}
    }
  ],
  "stats": {
    "execution_time_ms": 3.21,
    "nodes_scanned": 1,
    "edges_traversed": 0,
    "results_returned": 1
  }
}

5. Try Interactive Queries

Visit the KQL Syntax page and enter your API endpoint and wallet address to run interactive queries right in the browser!

API Reference

Query Endpoint

POST /api/v1/query

Headers:

• X-Wallet-Address: YOUR_WALLET_ADDRESS
• Content-Type: application/json

Body:

{
  "query": "MATCH (n) RETURN n LIMIT 10"
}

Write Endpoint

POST /api/v1/write

Headers:

• X-Wallet-Address: YOUR_WALLET_ADDRESS
• Content-Type: application/json

Body:

{
  "operations": [
    {
      "operation": "create_node",
      "label": "Person",
      "properties": {
        "name": {"String": "Alice"}
      }
    }
  ]
}

Stats Endpoint

GET /api/v1/stats

Headers:

• X-Wallet-Address: YOUR_WALLET_ADDRESS

Returns database statistics:

{
  "node_count": 1234,
  "edge_count": 5678,
  "node_labels": {"Person": 100, "Product": 200},
  "edge_types": {"KNOWS": 50, "PURCHASED": 150}
}

Next Steps

• Learn KQL syntax for powerful graph queries
• Explore pattern matching for complex traversals
• Check out filtering with WHERE clauses
• See return statements for data projection

Need Help?

• Email: support@knowledgedataflow.org
• Docs: docs.knowledgedataflow.org
• Hosted Service: db.knowledgedataflow.org