API Endpoints

KnowledgeFlowDB exposes a comprehensive REST API. Base URL: https://api.knowledgedataflow.org

All authenticated endpoints accept either X-Wallet-Address or Authorization: Bearer <token> headers. See Wallet Authentication for details.

Health

Method	Endpoint	Auth	Description
GET	/health	No	Health check and system status
GET	/api/v1/status	No	Detailed system status with protection state
GET	/api/v1/docs	No	Self-documenting API reference (JSON)

Query

Method	Endpoint	Auth	Description
POST	/api/v1/query	Yes	Execute a KQL query (routed to ClickHouse)
POST	/api/v1/query/sql	Yes	Execute a SQL query (routed to ScyllaDB)
POST	/api/v1/query/explain	Yes	Explain a KQL query plan without executing
GET	/api/v1/stats	Yes	Database statistics (node/edge counts)

Query Request Body

{
  "query": "MATCH (n:File) RETURN n.path, n.size LIMIT 10"
}

Write

Method	Endpoint	Auth	Description
POST	/api/v1/write	Yes	Create/update/delete nodes and edges
POST	/api/v1/bulk/upload	Yes	Bulk import JSON data

Write Request Body

{
  "operations": [
    {
      "operation": "create_node",
      "label": "Document",
      "properties": {
        "title": {"String": "My Document"},
        "version": {"Integer": 1}
      }
    }
  ]
}

Supported operations: create_node, update_node, delete_node, create_edge, delete_edge.

Entities

Method	Endpoint	Auth	Description
GET	/api/v1/entities/labels	Yes	List all node labels
GET	/api/v1/entities/{label}	Yes	List entities by label (supports ?limit=N)
GET	/api/v1/entities/{label}/{id}	Yes	Get a specific entity by label and ID

Search

Method	Endpoint	Auth	Description
POST	/api/v1/search/code	Yes	Multi-stream code search with RRF fusion
POST	/api/v1/search/semantic	Yes	Vector similarity search
POST	/api/v1/search/index	Yes	Index a document for full-text search
GET	/api/v1/search/indices	Yes	List search indices

Semantic

Method	Endpoint	Auth	Description
POST	/api/v1/embed	Yes	Generate embedding for text
POST	/api/v1/embed/multimodal	Yes	Generate multimodal embedding
GET	/api/v1/ast/{file_id}	Yes	Get AST symbols for a file

Sessions

Method	Endpoint	Auth	Description
GET	/api/v1/sessions	Yes	List tracked sessions
POST	/api/v1/sessions	Yes	Create a new session
GET	/api/v1/sessions/{id}	Yes	Get session details

Notes & Workspaces

Method	Endpoint	Auth	Description
POST	/api/v1/workspaces	Yes	Create a workspace
GET	/api/v1/workspaces	Yes	List workspaces
POST	/api/v1/notes	Yes	Create a note
GET	/api/v1/notes/{id}	Yes	Get a note
POST	/api/v1/notes/{id}/publish	Yes	Publish a note
GET	/api/v1/public/notes	No	List published notes

Tasks

Method	Endpoint	Auth	Description
POST	/api/v1/tasks	Yes	Create a task
GET	/api/v1/tasks	Yes	List tasks
PUT	/api/v1/tasks/{id}	Yes	Update a task

GitHub

Method	Endpoint	Auth	Description
POST	/api/v1/github/import	Yes	Import a GitHub repository
GET	/api/v1/github/context/{repo}	Yes	Get context bundle for a repository

Blockchain

Method	Endpoint	Auth	Description
GET	/api/v1/blockchain/transactions	Yes	Query blockchain transactions
GET	/api/v1/blockchain/wallets	Yes	Query wallet data

Admin

Method	Endpoint	Auth	Description
GET	/api/v1/tenants	Yes	List tenants
POST	/api/v1/backup	Yes	Trigger a backup
GET	/api/v1/system/events	Yes	Query system events

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "Description of what went wrong",
  "status": 400
}

Status	Meaning
400	Bad request (invalid query, missing fields)
401	Authentication required
402	Payment required (x402)
404	Resource not found
429	Rate limited
500	Internal server error