RESTORE DATABASE to a `timestamp` (each table as of its last version committed at or before it) or
const url = 'https://example.com/datanotes/operations/restore_database/';const options = { method: 'POST', headers: { 'X-Datanotes-Actor': '{"harness":"my-script","model":"","session":"s-1"}', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"timestamp":null,"before_migration":null,"dry_run":false}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/datanotes/operations/restore_database/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Datanotes-Actor: {"harness":"my-script","model":"","session":"s-1"}' \ --data '{ "timestamp": null, "before_migration": null, "dry_run": false }'RESTORE DATABASE to a timestamp (each table as of its last version committed at or before it) or
to before_migration (a migration_id or a batch: every table as it was just before that operation
ran — to rewind an agent’s run). Every table that keeps a transaction log goes back, rows and
definition: rows added since are deleted, changed rows get their old content, removed rows come back;
a table created since is dropped with its rows moved to its archive folder (as drop_table with
mode “archive”: nothing is hard-deleted), a table dropped since comes back. Tables already as
they were are left alone (unchanged, no new version). One operation: each restored table gets a
RESTORE version, all with one migration_id, and undo_migration on it reverts them all. Refused as a
whole, nothing written (rows listed, with the way out), when a row it leaves would break a CHECK that
follows links or a ref_where / ref_by, across tables, as the restored definitions have them.
Tables without a log (history off, or vacuumed before that time) cannot be rewound: they stay as they
are, listed in skipped with the reason (tell the user). Views, bases and the database settings are
not rewound (the logs keep tables), nor a rename or move of a table (undo_migration on it does that).
Returns restored_to, tables (per table: action restore / drop / recreate, version,
creates, texts, deletes, archived), unchanged and skipped. Run with dry_run first and show the user what changes; describe_history without table shows the moments.
The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”JSON: on whose behalf the write is made, recorded in the journal (harness, model, session).
Example
{"harness":"my-script","model":"","session":"s-1"}Request Body
Section titled “Request Body”Responses
Section titled “Responses”Done.
Result of restore_database: a write operation’s result plus what it does to each table. A refusal (ok false) is answered with HTTP 422, a failed write with 500, so a 2xx body has ok true.
object
True when the operation was applied (or, on a dry run, would be).
The operation, by the name it was called with (e.g. insert_row, create_table, recompute_columns).
True when nothing was written (preview).
Journal id of the applied operation: pass it to undo_migration. Absent on a dry run.
Notes whose front matter or body were written.
Files created.
Files moved or renamed.
Files deleted or archived.
Links rewritten in other notes.
Reasons the operation was refused (empty on success).
object
Note or file path.
Why the operation cannot proceed.
Rows that would break the table’s rules (empty on success).
The violations of one row.
object
Row note path.
What is wrong with this row.
object
The column the violation is about (every code but check and unreadable).
The item of a list column that breaks the rule, from 0.
The CHECK’s name (code check).
Kind of violation.
Agent-readable explanation.
The offending value, when there is one.
Files that could not be written (empty on success).
object
Vault path.
What went wrong.
Set when a write failed partway (failed): true when the engine put back what it had written, so nothing is left written; false when that rollback failed too (failed names the files left, and undo_migration on migration_id retries it).
Front matter edits per note (planned, or made).
object
Note path.
Front matter keys set, with their new values.
object
Front matter keys removed.
True when the note body changes too.
Paths of notes created.
Files moved: from → to.
object
Paths deleted (or archived).
Files rewritten whole, e.g. metastore.yaml for DDL.
Transaction-log commits written (tables with history on).
object
Qualified table.
New log version.
Log operation, e.g. WRITE.
Links the write added to the text it wrote: the notes the text mentions by name (automatic links). Present when there is one.
A link the write added in place of a mention.
object
The note the link was written into.
The mention, as written.
Vault path of the note it links.
The link written in place of the mention.
Mentions left as text because the engine is not sure which note they name. Present when there is one: read the candidates and the context, then link the right one with update_row and autolink: false, or leave the text.
A mention left as text: more than one note could be meant.
object
The note the mention is in.
The mention, as written.
Same_name: several notes have this name; adjacent: names of different notes side by side, which may be one name; overlap: names of notes overlap; part_of_name: a capitalized word next to it suggests a longer name; sentence_start: a one-word name at the start of a sentence, a line, a list item or a label, where its capital says nothing.
Vault paths of the notes it may name.
The line around the mention.
What to do: read the candidates, then link the right one with update_row and autolink: false, or leave the text.
The moment restored (ISO date-time): timestamp, or the last millisecond before the first commit of before_migration; given back as timestamp, it names the same state.
The tables that change.
object
Qualified table.
Restore: rows and/or definition go back; drop: the table did not exist then (definition removed, rows archived); recreate: dropped since, it comes back.
Its entry in metastore.yaml changes.
Rows re-created.
Rows that get their old text back.
Rows created since, deleted (undo puts them back).
Rows of a dropped table moved to its archive folder.
object
Logged tables already as they were then (no new version).
Tables that cannot be rewound (no transaction log, or not that far back), with the reason.
object
Example
{ "violations": [ { "violations": [ { "code": "required" } ] } ], "ambiguous_mentions": [ { "reason": "same_name" } ], "tables": [ { "action": "restore" } ]}Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}Missing or wrong bearer token.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}A named token beyond its permissions (the engine’s administration, tables outside its write patterns, schema changes without ddl).
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}Refused (validation failures, conflicts, an unmet expect): nothing written. Same body as 200, with ok: false and the reasons.
Result of restore_database: a write operation’s result plus what it does to each table. A refusal (ok false) is answered with HTTP 422, a failed write with 500, so a 2xx body has ok true.
object
True when the operation was applied (or, on a dry run, would be).
The operation, by the name it was called with (e.g. insert_row, create_table, recompute_columns).
True when nothing was written (preview).
Journal id of the applied operation: pass it to undo_migration. Absent on a dry run.
Notes whose front matter or body were written.
Files created.
Files moved or renamed.
Files deleted or archived.
Links rewritten in other notes.
Reasons the operation was refused (empty on success).
object
Note or file path.
Why the operation cannot proceed.
Rows that would break the table’s rules (empty on success).
The violations of one row.
object
Row note path.
What is wrong with this row.
object
The column the violation is about (every code but check and unreadable).
The item of a list column that breaks the rule, from 0.
The CHECK’s name (code check).
Kind of violation.
Agent-readable explanation.
The offending value, when there is one.
Files that could not be written (empty on success).
object
Vault path.
What went wrong.
Set when a write failed partway (failed): true when the engine put back what it had written, so nothing is left written; false when that rollback failed too (failed names the files left, and undo_migration on migration_id retries it).
Front matter edits per note (planned, or made).
object
Note path.
Front matter keys set, with their new values.
object
Front matter keys removed.
True when the note body changes too.
Paths of notes created.
Files moved: from → to.
object
Paths deleted (or archived).
Files rewritten whole, e.g. metastore.yaml for DDL.
Transaction-log commits written (tables with history on).
object
Qualified table.
New log version.
Log operation, e.g. WRITE.
Links the write added to the text it wrote: the notes the text mentions by name (automatic links). Present when there is one.
A link the write added in place of a mention.
object
The note the link was written into.
The mention, as written.
Vault path of the note it links.
The link written in place of the mention.
Mentions left as text because the engine is not sure which note they name. Present when there is one: read the candidates and the context, then link the right one with update_row and autolink: false, or leave the text.
A mention left as text: more than one note could be meant.
object
The note the mention is in.
The mention, as written.
Same_name: several notes have this name; adjacent: names of different notes side by side, which may be one name; overlap: names of notes overlap; part_of_name: a capitalized word next to it suggests a longer name; sentence_start: a one-word name at the start of a sentence, a line, a list item or a label, where its capital says nothing.
Vault paths of the notes it may name.
The line around the mention.
What to do: read the candidates, then link the right one with update_row and autolink: false, or leave the text.
The moment restored (ISO date-time): timestamp, or the last millisecond before the first commit of before_migration; given back as timestamp, it names the same state.
The tables that change.
object
Qualified table.
Restore: rows and/or definition go back; drop: the table did not exist then (definition removed, rows archived); recreate: dropped since, it comes back.
Its entry in metastore.yaml changes.
Rows re-created.
Rows that get their old text back.
Rows created since, deleted (undo puts them back).
Rows of a dropped table moved to its archive folder.
object
Logged tables already as they were then (no new version).
Tables that cannot be rewound (no transaction log, or not that far back), with the reason.
object
Example
{ "violations": [ { "violations": [ { "code": "required" } ] } ], "ambiguous_mentions": [ { "reason": "same_name" } ], "tables": [ { "action": "restore" } ]}Unexpected error ({error}), or a write that failed partway and could not be rolled back: rolled_back: false, failed lists the files left (undo_migration on migration_id retries the rollback).
Result of restore_database: a write operation’s result plus what it does to each table. A refusal (ok false) is answered with HTTP 422, a failed write with 500, so a 2xx body has ok true.
object
True when the operation was applied (or, on a dry run, would be).
The operation, by the name it was called with (e.g. insert_row, create_table, recompute_columns).
True when nothing was written (preview).
Journal id of the applied operation: pass it to undo_migration. Absent on a dry run.
Notes whose front matter or body were written.
Files created.
Files moved or renamed.
Files deleted or archived.
Links rewritten in other notes.
Reasons the operation was refused (empty on success).
object
Note or file path.
Why the operation cannot proceed.
Rows that would break the table’s rules (empty on success).
The violations of one row.
object
Row note path.
What is wrong with this row.
object
The column the violation is about (every code but check and unreadable).
The item of a list column that breaks the rule, from 0.
The CHECK’s name (code check).
Kind of violation.
Agent-readable explanation.
The offending value, when there is one.
Files that could not be written (empty on success).
object
Vault path.
What went wrong.
Set when a write failed partway (failed): true when the engine put back what it had written, so nothing is left written; false when that rollback failed too (failed names the files left, and undo_migration on migration_id retries it).
Front matter edits per note (planned, or made).
object
Note path.
Front matter keys set, with their new values.
object
Front matter keys removed.
True when the note body changes too.
Paths of notes created.
Files moved: from → to.
object
Paths deleted (or archived).
Files rewritten whole, e.g. metastore.yaml for DDL.
Transaction-log commits written (tables with history on).
object
Qualified table.
New log version.
Log operation, e.g. WRITE.
Links the write added to the text it wrote: the notes the text mentions by name (automatic links). Present when there is one.
A link the write added in place of a mention.
object
The note the link was written into.
The mention, as written.
Vault path of the note it links.
The link written in place of the mention.
Mentions left as text because the engine is not sure which note they name. Present when there is one: read the candidates and the context, then link the right one with update_row and autolink: false, or leave the text.
A mention left as text: more than one note could be meant.
object
The note the mention is in.
The mention, as written.
Same_name: several notes have this name; adjacent: names of different notes side by side, which may be one name; overlap: names of notes overlap; part_of_name: a capitalized word next to it suggests a longer name; sentence_start: a one-word name at the start of a sentence, a line, a list item or a label, where its capital says nothing.
Vault paths of the notes it may name.
The line around the mention.
What to do: read the candidates, then link the right one with update_row and autolink: false, or leave the text.
The moment restored (ISO date-time): timestamp, or the last millisecond before the first commit of before_migration; given back as timestamp, it names the same state.
The tables that change.
object
Qualified table.
Restore: rows and/or definition go back; drop: the table did not exist then (definition removed, rows archived); recreate: dropped since, it comes back.
Its entry in metastore.yaml changes.
Rows re-created.
Rows that get their old text back.
Rows created since, deleted (undo puts them back).
Rows of a dropped table moved to its archive folder.
object
Logged tables already as they were then (no new version).
Tables that cannot be rewound (no transaction log, or not that far back), with the reason.
object
object
What went wrong, for a person or an agent.
Example
{ "violations": [ { "violations": [ { "code": "required" } ] } ], "ambiguous_mentions": [ { "reason": "same_name" } ], "tables": [ { "action": "restore" } ]}A write that failed partway (a file another program holds) and was rolled back: rolled_back: true, nothing written. Send it again later. Same body as 200, with ok: false and failed.
Result of restore_database: a write operation’s result plus what it does to each table. A refusal (ok false) is answered with HTTP 422, a failed write with 500, so a 2xx body has ok true.
object
True when the operation was applied (or, on a dry run, would be).
The operation, by the name it was called with (e.g. insert_row, create_table, recompute_columns).
True when nothing was written (preview).
Journal id of the applied operation: pass it to undo_migration. Absent on a dry run.
Notes whose front matter or body were written.
Files created.
Files moved or renamed.
Files deleted or archived.
Links rewritten in other notes.
Reasons the operation was refused (empty on success).
object
Note or file path.
Why the operation cannot proceed.
Rows that would break the table’s rules (empty on success).
The violations of one row.
object
Row note path.
What is wrong with this row.
object
The column the violation is about (every code but check and unreadable).
The item of a list column that breaks the rule, from 0.
The CHECK’s name (code check).
Kind of violation.
Agent-readable explanation.
The offending value, when there is one.
Files that could not be written (empty on success).
object
Vault path.
What went wrong.
Set when a write failed partway (failed): true when the engine put back what it had written, so nothing is left written; false when that rollback failed too (failed names the files left, and undo_migration on migration_id retries it).
Front matter edits per note (planned, or made).
object
Note path.
Front matter keys set, with their new values.
object
Front matter keys removed.
True when the note body changes too.
Paths of notes created.
Files moved: from → to.
object
Paths deleted (or archived).
Files rewritten whole, e.g. metastore.yaml for DDL.
Transaction-log commits written (tables with history on).
object
Qualified table.
New log version.
Log operation, e.g. WRITE.
Links the write added to the text it wrote: the notes the text mentions by name (automatic links). Present when there is one.
A link the write added in place of a mention.
object
The note the link was written into.
The mention, as written.
Vault path of the note it links.
The link written in place of the mention.
Mentions left as text because the engine is not sure which note they name. Present when there is one: read the candidates and the context, then link the right one with update_row and autolink: false, or leave the text.
A mention left as text: more than one note could be meant.
object
The note the mention is in.
The mention, as written.
Same_name: several notes have this name; adjacent: names of different notes side by side, which may be one name; overlap: names of notes overlap; part_of_name: a capitalized word next to it suggests a longer name; sentence_start: a one-word name at the start of a sentence, a line, a list item or a label, where its capital says nothing.
Vault paths of the notes it may name.
The line around the mention.
What to do: read the candidates, then link the right one with update_row and autolink: false, or leave the text.
The moment restored (ISO date-time): timestamp, or the last millisecond before the first commit of before_migration; given back as timestamp, it names the same state.
The tables that change.
object
Qualified table.
Restore: rows and/or definition go back; drop: the table did not exist then (definition removed, rows archived); recreate: dropped since, it comes back.
Its entry in metastore.yaml changes.
Rows re-created.
Rows that get their old text back.
Rows created since, deleted (undo puts them back).
Rows of a dropped table moved to its archive folder.
object
Logged tables already as they were then (no new version).
Tables that cannot be rewound (no transaction log, or not that far back), with the reason.
object
Example
{ "violations": [ { "violations": [ { "code": "required" } ] } ], "ambiguous_mentions": [ { "reason": "same_name" } ], "tables": [ { "action": "restore" } ]}