API Endpoints
KnowledgeFlowDB exposes a REST API at:
https://api.knowledgedataflow.org
Auth Contract
For hosted interactive usage, the normal auth contract is:
Authorization: Bearer <token>
x-derive-session-id: <session_id>
x-derive-key: <derive_key_hex>
The docs app attaches those headers automatically after Privy login.
Advanced programmatic clients may use bearer tokens or API keys directly. X-Wallet-Address remains a compatibility path only where older tooling still expects it.
Health
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /health | No | Health check |
| GET | /api/v1/status | No | Detailed system status |
| GET | /api/v1/docs | No | JSON API docs |
Wallet / Derive Auth
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /auth/challenge | No | Get wallet auth challenge |
| POST | /auth/verify | No | Exchange signed challenge for bearer token |
| POST | /api/v1/auth/derive-challenge | No | Get sign-to-derive challenge |
| POST | /api/v1/auth/derive-key | No | Register derive session from signed payload |
See Wallet Authentication for the full flow.
Query
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/v1/query | Yes | Execute KQL |
| POST | /api/v1/query/sql | Yes | Execute SQL |
| POST | /api/v1/query/explain | No | Explain plan without execution |
| GET | /api/v1/stats | Yes | Database statistics |
Discovery / Schema
The primary discovery surface is through query HELP and SHOW commands:
HELP
SHOW LABELS
SHOW EDGE_TYPES
SHOW PROPERTIES File
SHOW SCHEMA
Tenant / Hosted Service
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/tenant/me | Yes | Get current tenant status |
| POST | /api/v1/tenant/activate | Yes | Activate current tenant plan |
| POST | /api/v1/tenants/create | No | Public tenant creation route |
| GET | /api/v1/tenant/plans | No | Available plans |
Data APIs
| Category | Examples |
|---|---|
| Graph writes | /api/v1/write, /api/v1/bulk/upload |
| Entities | /api/v1/entities/labels, /api/v1/entities/{label} |
| Notes | /api/v1/notes, /api/v1/public/notes |
| Workspaces | /api/v1/workspaces |
| Tasks | /api/v1/tasks |
| Sessions | /api/v1/sessions |
| Search | /api/v1/search, /api/v1/semantic/search |
| Automation | /api/v1/automation/* |
Error Format
Errors are returned as structured JSON. The exact shape varies slightly by endpoint, but you should expect an HTTP status plus an error/message payload.
Common statuses:
| Status | Meaning |
|---|---|
| 400 | Invalid input or malformed query |
| 401 | Authentication required |
| 403 | Authenticated but missing required user-key/permission context |
| 404 | Resource not found |
| 429 | Rate limited |
| 500 | Internal server error |