Skip to content
Datanotes
Search
Ctrl
K
Cancel
GitHub
Menu
Get Started
Overview
Run Datanotes on Your Notes
Connect Your Agents
How It Works
Guides
Database Objects
Catalogs and Schemas
Tables
Columns and Types
Views
Bases
Relations and Hierarchies
Data Quality
Validation
CHECK Constraints
Hand Edits
check_table
Sync Between Devices
Read and Write Data
Read and Filter
Joins and Aggregates
Write and Move Rows
Automatic Links
Batch
Import Existing Notes
Search
Text Search
Semantic Search
Link Graph
History and Recovery
Journal and Undo
Table History and Time Travel
Change Data Feed
Restore
Vacuum
Back Up the History
Agents
How Agents Use Datanotes
Prompts
Reading Errors
Docs Offline
Security
Tokens and Permissions
Who Did What
Security Model
Develop
HTTP API
JavaScript Client
Concurrency
Build an App
Build on Datanotes
Change Feed and Webhooks
Logs and Telemetry
Reference
Operations
Overview
Schema (DDL)
Rows (DML)
Queries
History
Auxiliary
HTTP API reference
Overview
Schema (DDL)
Overview
Create a table: `name`, in `catalog` and `schema` (default: the database's defaults); the definition
Drop a table. Refused while it has rows unless `mode: "archive"`, which removes the
Add a typed column. Sparse by default (written only on rows that have a value — use for
Rename a column in metastore.yaml and on every row. Refused if `to_column` is already a column
Remove a column from the schema and every row. Previous values are journaled; revert with
Change a column's attributes (type, min/max/step, values, required, default, label,
Alter a table: move it (`catalog`, `schema`), rename it (`name`), change
Create or replace a base: a named set of columns (same spec as `create_table`) that tables
Set the bases a table inherits from (`bases`, in order; `[]` removes them). Inherited
COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its
Rename one value of an enum column (e.g. `high` → `very high`) in metastore.yaml and every
ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match,
Remove the CHECK constraint `name` from `table`.
Create (or `replace`) a view: a named select stored in metastore.yaml. Name it with the prefix
Remove a view from `metastore.yaml` (undo with `undo_migration`).
CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows
Rows (DML)
Overview
Insert a row (new note). Values are validated against the columns; the note path comes from
Update every row matching `where` (required: `{}` is every row). `where`: keys AND-ed; values are equality or operators
Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when
Delete rows matching `where`. `mode`: "archive" (default, move to the table's archive
Move rows matching `where` (required: `{}` is every row) to another table (e.g. split a domain out of `log` into its own
Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and
Several writes that succeed or fail together. `operations`: `[{"op": ..., ...arguments}]` where
Add the reciprocal links missing on a table's `inverse` link columns (e.g. Alice lists Carol
MERGE (upsert) `rows` into `table` by the key columns `on` (e.g. `["occurred_at"]` or
Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after
Queries
Overview
Read a note or another file of the vault: `{path, content, front_matter, tags, modified_at,
The direct children of a vault folder: `{folder, folders, files}`, each a vault path, sorted;
Plain-text search: every word of `query` must occur, case- and accent-insensitive, in the
Query rows: `{table, total, rows: [{path, ...}]}`. `table` may be a view,
The rows a link column may point to, for one row: what an agent or a picker offers before writing
Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,
Direct neighbours of notes: what they link to (`out`) and what links to them (`in`,
Breadth-first walk over links from `from_nodes` (`{"paths": [...]}` and/or `{"table", "where"}`).
Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or
History
Overview
Revert a journaled table operation by its `migration_id`. Refused (nothing written) when any
The operation journal, newest first: `total` (the matching operations) and `migrations`, each with
DESCRIBE HISTORY: the table's versions, newest first — `version`, `timestamp`, `operation`
Change data feed between two versions (both included, end defaults to latest): one entry
Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes
Webhooks of the change feed: id, url, filter (tables, ops, columns, exclude_actor), `cursor` (last change delivered), `status` (ok, failing, disabled), `last_delivery`, `last_error`. Secrets are not shown.
Push row changes to a URL (a service that would rather be called than poll `list_changes`): batches of up to 100 events POSTed as `{webhook, events, last}`, signed with `X-Datanotes-Signature: sha256=<HMAC of the body>`, retried with backoff until a 2xx. Events are those of `list_changes` (hand edits with their `violations`; the hand edits the service has seen are recorded before it stops). Starts from now unless `since`. Returns the webhook with its `secret` — shown only here: give it to the receiver. Only on the user's explicit request: a webhook sends the database's changes (and, with `since`, its past ones) to that address.
Stop and remove a webhook (by `id` from list_webhooks).
RESTORE TABLE to a `version` or `timestamp`: rows and definition return to that state —
RESTORE DATABASE to a `timestamp` (each table as of its last version committed at or before it) or
Delete transaction-log history older than `retain_from_version` (default: keep only the
Auxiliary
Overview
List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it
Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`,
Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely,
Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database
Validate every row against the table (required, types, ranges, enums, links, unknown
Read-only schema inference from notes' front matter.
The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`,
Bring the semantic search index up to date: embed the notes changed since the last run (the
change feed
Overview
Record an agent's tool call in the change feed (`tool_call` events): what an MCP server reports after each call, its own tools included (`served_by`). Any token may call it.
The change feed as Server-Sent Events (id = sequence number). Resumes from Last-Event-ID or `since`.
tokens
Overview
Tell the engine the model and harness behind an agent session (what an MCP server reports): later requests carrying that session in `X-Datanotes-Actor` are journaled with it. Any token may call it.
List the named tokens (owner only).
The calling token's own entry (a named token; 400 for the owner).
Create a named token (owner only). Returns the token once.
Change a named token. A token may change its own description and autolink default; permissions are the owner's.
Revoke a named token (owner only): it stops working at once.
Give a named token a new value (owner only): the old one stops working.
service
Overview
The sections of the docs of this version closest in meaning to a query: what `search_docs` fuses with its ranking by words (hybrid search).
The engine's health at a glance (owner only; `datanotes status` prints it): engine, database, journal, git sync, change feed, webhooks, named tokens, hand edits breaking the rules in the last 24 h, logs.
Stop the engine gracefully (owner only; `datanotes stop` calls it): it answers at once, then finishes the requests under way, makes the last git sync and store backup commit and push, releases its lock and exits.
This document (as `GET /datanotes/openapi.json`, with a token).
Status and version (no token needed; `authenticated` tells whether the token sent is accepted, `auth` whose it is).
This document (public: it describes the API, it holds no data).
This document in an interactive console (Swagger UI, served by the engine; public). Authorize with a token to try the routes.
The index of the docs of this version (every page of datanotes.dev as Markdown, shipped with the package): each page with its description and route.
A page of the docs of this version as Markdown, or one of its sections with `section`, the anchor of its heading. The same text as the page with `.md` on datanotes.dev, offline.
CLI
Settings
Errors
Compatibility
Glossary
Administration
Run the Service
Run in Docker
Git Sync
Datanotes Status
Configuration
Use with Obsidian
Limits
Release Notes
GitHub
Overview
Schema (DDL)
Section titled “Schema (DDL)”
Operations that define the database: tables, columns, constraints, bases and views.
Operations
Section titled “Operations”
POST
/datanotes/operations/create_table/
POST
/datanotes/operations/drop_table/
POST
/datanotes/operations/add_column/
POST
/datanotes/operations/rename_column/
POST
/datanotes/operations/drop_column/
POST
/datanotes/operations/alter_column/
POST
/datanotes/operations/alter_table/
POST
/datanotes/operations/define_base/
POST
/datanotes/operations/set_table_bases/
POST
/datanotes/operations/comment_on/
POST
/datanotes/operations/rename_value/
POST
/datanotes/operations/add_constraint/
POST
/datanotes/operations/drop_constraint/
POST
/datanotes/operations/create_view/
POST
/datanotes/operations/drop_view/
POST
/datanotes/operations/clone_table/