Repository Public
1# SP Note 3.0 — API contract of the backend foundation (`API-NEXT.md`)23Reference for the native clients (SPNotesCore 2.0, SP Notes macOS / iOS 2.0) and the web client. It specifies what the backend4workstream added for « Next Generation » (SPEC v1, 2026-11-19): change feed for entities, tasks, events journal, time machine,5knowledge graph 2.0, canvas, knowledge health, brief, living blocks, semantic zoom (levels 2–3), the document layer of the new nodes,6and the defects fixed. Everything that existed in 2.x keeps its path and its shape (see `docs/architecture.md` and audit-web §2); only7the differences are written here.89**Every JSON example in this file is a real answer** of the scratch instance (`note_next_dev`, branch `next`), recorded by10`scripts/next-api-examples.ts` on 2026-11-19T23:28:08.296Z and inlined by `scripts/next-api-doc.py`. Do not edit `API-NEXT.md` by hand: edit11`API-NEXT.template.md`. The AI workstream documents its part in `docs/next/API-NEXT-AI.md`; its sections are marked12`<!-- AI-WORKSTREAM -->` below.1314Contents: [0 Conventions](#0-conventions) · [1 Meta](#1-meta) · [2 Document format](#2-document-format--new-nodes) ·15[3 Change feed](#3-change-feed--get-apisync) · [4.2 Tasks](#42-tasks) · [4.3 Graph](#43-knowledge-graph-20) ·16[4.4 Events & time machine](#44-events-journal-and-time-machine) · [4.5 Health](#45-knowledge-health) · [4.6 Brief](#46-brief) ·17[4.7 Query](#47-living-blocks--post-apiquery) · [4.8 Canvas](#48-canvas) · [4.9 Zoom](#49-semantic-zoom) ·18[4.15 Files, purge, ids, cycles](#415-files-purge-identifiers-parent-cycles) · [5 Error codes](#5-error-codes) ·19[6 Deviations and limits](#6-deviations-from-spec-v1-and-known-limits) · [7 Testing against the scratch instance](#7-testing-against-the-scratch-instance)2021---2223## 0. Conventions2425### 0.1 Authentication, same-origin rule, headers2627Unchanged from 2.x. Every route below needs the session cookie (`__Host-note_session=<token>`; the cookie name is `note_session`28only under `next dev`). Without it: `401 {"error":"Sign-in required","code":"unauthenticated"}`.2930Every `POST` / `PUT` / `PATCH` / `DELETE` must carry `Origin: <APP_URL origin>` (exactly the origin of the server, e.g.31`https://note.spboucher.ai`), else `403 {"code":"csrf"}`. `POST /api/query` is a read, but it is a POST: it needs `Origin` too.3233Send `User-Agent: SPNotes/<version> (Macintosh|iPhone|iPad; …)`: the device label derived from it (`SP Notes · Mac`, …) is stored in34every journal event written while serving the request (`device`).3536Responses: `Content-Type: application/json`, `Cache-Control: private, no-store`, `x-request-id`. Dates are ISO 8601 UTC with37milliseconds (`2026-11-19T18:22:18.475Z`). Ids are lower-case UUIDs unless stated (block ids are 10-character strings from38`0-9a-zA-Z_-`; canvas node / edge ids are client strings of 1–64 characters).3940### 0.2 Errors4142```json43{ "error": "human message (English)", "code": "machine_code", "...": "extra fields for some codes" }44```4546**Every error answer carries a stable `code`** (integration pass, 2026-11-19: several 2.x and 3.0 answers had none). `code` is what47clients test — never the English message. When the service gives no specific code, the code is the default of the HTTP status:4849| HTTP | default `code` | | HTTP | default `code` |50|---|---|---|---|---|51| 400 | `bad_request` | | 413 | `too_large` |52| 401 | `unauthenticated` | | 415 | `unsupported_media_type` |53| 403 | `forbidden` | | 422 | `unprocessable` |54| 404 | `not_found` | | 429 | `rate_limited` |55| 409 | `invalid_state` | | 500 | `internal` (`{"error":"Internal error","code":"internal","requestId":"…"}` — always a server bug) |56| 410 | `gone` | | 501 / 502 / 503 | `not_implemented` / `upstream_error` / `unavailable` |5758Since 3.0 **malformed input never answers 500**: a path / query / body value that is not what the route expects (a non-UUID id, an59unparsable date, an unknown enum value, a body that fails its schema — `"error": "Validation: <field> <reason>; …"` —, invalid JSON)60answers `400 bad_request` unless a more specific code is documented. A well-formed id that does not exist answers `404 not_found`.61The full list of specific codes is in [§5](#5-error-codes).6263### 0.3 Idempotency6465Two mechanisms, both usable together:66671. **Client-chosen id** (preferred for offline creation). Every create route of a synchronised kind accepts a UUID `id`; sending the68 same `id` again returns the **stored** object, untouched, with status `200` and the header `x-existing: 1` (first time: `201`).69 A retry never overwrites and never resurrects: if the object was edited, completed or deleted meanwhile, that state is returned.70 An id that belongs to another workspace → `409 id_taken`.7172 | Kind | Create route | Notes |73 |---|---|---|74 | page (incl. canvas) | `POST /api/pages` `{id}` | 2.x; `type: "canvas"` is new |75 | attachment | `POST /api/attachments` (multipart field `id`) | 2.x |76 | task | `POST /api/tasks` `{id}` | new |77 | edge (typed relation) | `POST /api/graph/relations` `{id}` | new |78 | concept | `POST /api/concepts` `{id}` | new |79 | reference | `POST /api/research/references` `{id}` | new field; a known id answers `200` + `x-existing: 1` with the stored row (it answered `201` before the integration pass); the id of a **deleted** reference → `409 reference_deleted` `{id, deletedAt}` — a retry never resurrects; bring it back with `POST /api/research/references/<id>?action=restore` |80 | database | created with its host page (`POST /api/pages` `{id, type:"database"}`); the database object gets a server id the first time the database is opened (`GET /api/databases/<pageId>`) | every database route accepts the host page id in place of the database id |81 | database_property | `POST /api/databases/<db>/properties` `{id}` | new field; answers `201` both times |82 | database_view | `POST /api/databases/<db>/views` `{id}` | new field; answers `201` both times |83 | database_row | `POST /api/databases/<db>/rows` `{id, pageId}` (`pageId` = id of the row's page) | new fields; answers `201` both times; a row id whose row was deleted → `409 row_deleted` |84 | canvas | no create route: the row is born with its page; `PUT /api/canvases/<pageId>` is naturally idempotent | |85862. **`Idempotency-Key`** header (2.x, unchanged): any mutating request carrying it runs at most once; the stored 2xx JSON answer is87 replayed with `idempotent-replay: true`.8889### 0.4 `rev` and `version`9091- `rev` (integer, one sequence for the whole workspace) is the **change signal**: it grows every time a row changes for any reason.92 It orders the change feed. Compare revs only for equality / order; never do arithmetic on them.93- `version` (pages, canvases) is the **edit guard**: it grows by one when a client-visible edit is saved (page: title, content or94 properties; canvas: `data`) and is what `baseVersion` is compared with.9596A row can therefore move in the feed (`rev`) **without** a new `version`: metadata (pin, archive, move, tags), and server-assigned97block ids (the background back-fill that gives ids to blocks and list items written before they had one). Rule for clients: *when a98row arrives with a new `rev` and there is no pending local edit for it, replace the local copy, whatever its `version`*. With a99pending local edit, keep the local copy and save it with the `baseVersion` you hold: if the versions match the save is accepted.100101Block ids are **stable** since 3.0: when a saved document contains a block without `id` (a client that never received the ids), the102server gives it back the id the same block (same type, same text, document order) had in the stored document; only a really new block103gets a fresh id. A client never needs to merge ids by hand.104105---106107### 0.5 DELETE is idempotent108109One rule for every `DELETE` (integration pass): **deleting something that is already gone — deleted by an earlier call, or never110existing — answers the same `200` as the first call**, with the same body keys (`{"ok":true}`; routes that report what they did say111so truthfully: `"deleted": false`, `"deleted": 0`, `"purged": 0`, `"extract": null`). Nothing is written the second time (no event,112no audit entry, no new `rev`). A `DELETE` answers an error only when:113114- the id is malformed → `400 bad_request`;115- a **container** named in the path does not exist → `404 not_found` (`/api/databases/<unknown>/…`, `/api/research/references/<unknown>/extracts`);116- the object exists and may not be deleted this way → `409 derived_edge` (document link, citation, link suggestion),117 `400 bad_request` (the title property of a database), `400 last_view` (the only view of a database);118- permanent deletion without a recent passkey verification → `403 reauth_required`.119120Applies to: `/api/pages/<id>`, `/api/tasks/<id>`, `/api/graph/relations/<id>`, `/api/concepts/<id>`, `/api/research/tasks/<id>`,121`/api/research/references/<id>`, `/api/research/experiments/<id>`, `/api/attachments?id=`, `/api/ai/conversations?id=`,122`/api/databases/<db>/views|properties|rows|row-templates?id=`, `/api/trash`. **One frozen exception**: the 2.x query form123`DELETE /api/tasks?id=<id>` still answers `404 not_found` for an unknown or already deleted task (kept byte-compatible; 3.0 clients124use `DELETE /api/tasks/<id>`).125126### 0.6 Dates, numbers, bare dates, clamping127128- Every date in every JSON answer is an ISO-8601 UTC string with milliseconds and every count is a JSON number. The integration pass129 removed the last raw PostgreSQL values (`"2026-11-19 13:45:47.060354-05"`, counts as strings): `updatedAt` of130 `GET /api/search` (quick mode), `calls / errors / inputTokens / outputTokens` of `GET /api/ai/usage`, the counters and131 `last_indexed` of `GET /api/search/index-state` (and `health.pending[].updatedAt`, `health.failed[].at`), `time` of `GET /api/health`.132- **A bare date** (`"2026-12-05"`) given as a due date means « that day » and is stored at **12:00 UTC** of that day — the same133 calendar day in every time zone from UTC−11 to UTC+11 — by every route: `POST | PATCH /api/tasks` (`dueAt` or `due`),134 `POST | PATCH /api/research/tasks` (`dueAt`; it stored 00:00 UTC before), and the `due` attr of a `taskItem`. A datetime with an135 offset is kept as given. Anything else → `400 bad_request`.136- **Numeric query parameters are clamped, not refused**, when they are integers outside their range: the nearest bound is used137 (`limit=0` → 1, `limit=999` → the maximum, `inactiveDays=0` → 1). The applied value is visible in the answer where the route138 echoes it (`inactiveDays`, `limit`). A value that is not an integer → `400 bad_request`.139140---141142## 1. Meta143144### `GET /api/meta`145146```http147GET /api/meta148```149150```http151HTTP 200152```153154```json155{156 "api": 3,157 "version": "3.0.0-dev",158 "features": [159 "entities",160 "tasks-v2",161 "events",162 "timemachine",163 "graph-v2",164 "insights",165 "canvas",166 "health",167 "brief",168 "query",169 "zoom",170 "nodes-v3",171 "files-range",172 "zoom-synopsis",173 "ask-scope",174 "actions-v2",175 "models-v2",176 "inbox-suggestions",177 "transcription",178 "research-export",179 "smart-properties",180 "constellation"181 ],182 "serverTime": "2026-11-19T23:28:08.058Z"183}184```185186`api` is the API level (3). `version` is `3.0.0` in production (a scratch build keeps its suffix). **Gate UI on `features`, never on187`version`.** Flags of this workstream: `entities`, `tasks-v2`, `events`, `timemachine`, `graph-v2`, `insights`, `canvas`, `health`, `brief`, `query`, `zoom`, `nodes-v3`, `files-range`, `zoom-synopsis`, `ask-scope`, `actions-v2`, `models-v2`, `inbox-suggestions`, `transcription`, `research-export`, `smart-properties`, `constellation`. The AI workstream appends its own (see `API-NEXT-AI.md`). A 2.x server188answers `404` on this route: treat that as `api: 2`, `features: []`.189190---191192## 2. Document format — new nodes193194ProseMirror JSON stays canonical; SPEC §2 defines the nodes and their attrs. This section specifies what the **server** does with them.195196### 2.1 Storage and validation197198- The server has **no allow-list of node types**: an unknown node (and an unknown attr of a known node) is stored and returned199 verbatim. Clients must do the same (neutral read-only card, never conversion, never deletion).200- `assertDoc` (every route that stores a document) keeps the 2.x structural limits (8 MiB, depth 60, 200 000 nodes, no201 `javascript:` URL) and adds bounds on the attrs of the 3.0 nodes. A violation answers `400 {"code":"bad_document","error":"Invalid document: <reason>"}`.202203| Node | Checks (a `null` / absent attr is always accepted) |204|---|---|205| `mermaid` | `code` string ≤ 200 000 chars; `preview` UUID; `previewHash` 64 hex chars |206| `drawing` | `ink`, `preview`, `pk` UUIDs |207| `runCode` | `code` ≤ 200 000 chars; `language` ≤ 64; `output.text` string ≤ 200 000 |208| `chart` | `columns`: ≤ 100 strings (each ≤ 2 000); `rows`: ≤ 5 000 arrays of ≤ 100 cells, a cell is string (≤ 2 000) \| number \| null; `title` ≤ 500 |209| `pdf` | `attachmentId` UUID; `name` ≤ 500; `annotations`: ≤ 2 000 objects, `text` / `note` ≤ 10 000 chars each, `rects` ≤ 500, `ink` ≤ 20 000 points |210| `audio` | `attachmentId` UUID; `title` ≤ 500; `transcript`: ≤ 20 000 `{t, text}` with `text` string ≤ 5 000; `summary.text` ≤ 20 000 |211| `queryView` | `databaseId`, `viewId` UUIDs; `title` ≤ 500; `limit` integer 1…500 |212| `blockRef` | `pageId` UUID; `blockId` ≤ 64 chars |213| `canvasLink` | `pageId` UUID |214| `citation` | `refId` UUID; `locator` ≤ 200; `label` ≤ 500 |215| `bibliography` | `style` ≤ 32; `title` ≤ 500 |216217An attachment is always referenced by its **id** (never a URL, never inline bytes): `"/api/files/<id>"` in an id attr is refused.218The same numbers are exported as `NEXT_LIMITS` in `src/lib/editor/next-nodes.ts`.219220### 2.2 Block ids221222Blocks that receive an `id` attr server-side when they lack one: the 14 types of 2.x (`paragraph, heading, blockquote, codeBlock,223bulletList, orderedList, taskList, table, callout, details, aiBlock, blockMath, image, fileBlock`) **plus `listItem`, `taskItem`** and224the ten new block atoms (`mermaid, drawing, chart, queryView, bibliography, pdf, blockRef, runCode, audio, canvasLink`). `citation` is225inline and has none. Ids are unique per document; a duplicate id (copy / paste) is replaced on the second occurrence.226227### 2.3 What saving a document does (server side)228229On every save of a page (`POST /api/pages`, `PATCH /api/pages/<id>`, restore, import, agent), in one transaction:230231| Found in the document | Effect |232|---|---|233| `mention` (not `kind:"user"`), `link` mark to `/p/<uuid>[#block-<blockId>]`, `blockRef`, `canvasLink` | page → page link: a row in `links` (kind `link`, the backlinks) and an **edge** `kind:"link"`, `relType:"related"`, `origin:"system"`, with `sourceBlockId` (the block that holds the reference) and `targetBlockId` (for `blockRef` / `#block-`). Only targets that are pages of the workspace. |234| `citation` with a `refId` that is a reference of the workspace | **edge** `kind:"cites"`, `relType:"cites"`, `origin:"system"`, `sourceKind:"page"`, `targetKind:"reference"`, `sourceBlockId` |235| `taskItem` with `taskId` | see [§4.2 Tasks and documents](#tasks-and-documents) |236| a new `aiBlock` (id not in the previous version) | event `ai.applied` |237| a new `callout` with `kind:"decision"` | event `decision.recorded` |238239Edges derived from a document disappear when the reference is removed from the document; they cannot be edited through the relations API.240241### 2.4 Export rules (Markdown, plain text) — byte-exact contract242243Implemented in `src/lib/editor/next-nodes.ts` (`nextNodeMarkdown`, `nextNodeText`), called by `toMarkdown` / `docText` in244`src/lib/editor/text.ts`. SPNotesCore `MarkdownExport` must produce the same bytes. **Fixtures**: `tests/fixtures/next-nodes/*.json`245with the expected `.md`, `.txt` (and `.html`) next to each — `all-nodes`, `defaults` (every attr at its default), `edge-cases`,246`mixed-document`. `tests/unit/next-nodes.test.ts` compares byte for byte.247248Common rules. A *label* is `oneLine(x)`: the string with every run of whitespace containing a newline replaced by one space, then249trimmed; a non-string is `""`. A *uuid* attr that is not a valid UUID is treated as `null` and written lower-case otherwise. In250Markdown every block ends with exactly one `\n`; top-level blocks are joined with `\n` (one blank line between them), runs of 3+251newlines collapse to 2, and the document is trimmed and ends with `\n` (2.x rules, unchanged).252253| Node | Markdown | Plain text (search index, word count) |254|---|---|---|255| `mermaid` | ```` ```mermaid\n<code>\n```\n ```` | `<code>` |256| `runCode` | ```` ```<language>\n<code>\n```\n ```` then, **iff `output` is an object with a string `text`** (even empty), `\n` + ```` ```output\n<output.text>\n```\n ```` | `<code>`, then `\n<output.text>` when it is non-empty |257| `chart` | no columns: `<title>\n`, or `[Graphique]\n` when the title is empty. With columns: `<title>\n\n` (omitted when empty) then a GFM table: header `\| c1 \| c2 \|`, separator `\| --- \| --- \|`, one line per row with exactly one cell per column (missing cells empty, extra cells ignored). Cells: `cellText`, then `\|` escaped as `\\\|` | lines joined by `\n`, empty lines dropped: title, columns joined by one space, each row's cells joined by one space (trimmed) |258| `drawing` | `\n`, or `[Dessin]\n` without a valid `preview` | `Dessin` |259| `pdf` | `[PDF: <name>](/api/files/<attachmentId>)\n` (`[PDF](…)` when the name is empty; no `(…)` part without a valid id), then, when there are annotations, a blank line and one line per annotation: `> ` + the non-empty parts of `p.<page>`, `<text>`, `<note>` joined by ` — ` (space, U+2014, space). `page` is floored, minimum 1 | `PDF: <name>` (or `PDF`), then the annotation lines without `> ` |260| `audio` | `[Audio: <title>](/api/files/<attachmentId>)\n` (same fallbacks as pdf), then, when the transcript has segments with text, a blank line and one line per segment: `[mm:ss] <text>` | `Audio: <title>` (or `Audio`), then one line per segment: `<text>` **without the time code** |261| `queryView` | `[Vue: <title>]\n`, or `[Vue]\n` | `Vue: <title>`, or `Vue` |262| `blockRef` | `[[<pageId>#<blockId>]]\n`; without block id `[[<pageId>]]\n`; without page id `[[]]\n` or `[[#<blockId>]]\n` | empty string |263| `citation` (inline) | `[@<label>]`; when the label is empty `[@<refId>]`; when both are missing `[@?]` | `<label>` (empty when there is none) |264| `bibliography` | `## <title>\n`; `## Références\n` when the title is empty | `<title>`, or `Références` |265| `canvasLink` | `[Canvas](/p/<pageId>)\n`, or `[Canvas]\n` without a valid page id | `Canvas` |266267`cellText(v)`: `null` / missing → empty; boolean → `true` / `false`; number → **ECMAScript `Number::toString`**: an integer-valued268finite number prints without a decimal point (`3`, never `3.0`; `-0` prints `0`), other finite numbers print the shortest decimal269that round-trips (`0.1`, `135.5`, `1e+21`, `1.5e-7`), `NaN` / `±Infinity` → empty; string → its label (newlines become one space).270271`[mm:ss]`: `t` floored to whole seconds (non-numbers and negatives → 0); `mm = ⌊t/60⌋` on at least two digits and **not capped at 59**272(`[125:03]`), `ss` on two digits.273274Transcript and annotation text are indexed for search (each new block atom is one search chunk carrying its block id); attachment,275page and block ids and time codes are not. `summary`, `output.error`, `ink`, `rects` are not exported.276277When an export rewrites attachment links (ZIP, standalone HTML / Markdown), `/api/files/<id>` in the forms above is replaced by the278resolved path; nothing else changes.279280HTML (print export, `?format=pdf|html`): `src/lib/export/next-nodes-html.ts`, one element per node with class `nx nx-<type>`; a chart281is its data table, a drawing / diagram its stored render, code is never executed. HTML is not part of the cross-platform contract.282283---284285## 3. Change feed — `GET /api/sync`286287`GET /api/sync?since=<rev>&limit=<1..500, default 200>[&kinds=<list>]`288289- **Without `kinds`** the answer is the 2.x one, byte for byte: same keys in the same order, tombstones of `page` and `attachment`290 only, and a `head` that ignores the revisions of the new kinds (a 1.x native client sees nothing new).291- **With `kinds`** — a comma list among `task`, `database`, `database_property`, `database_view`, `database_row`, `edge`, `reference`, `canvas`, `concept`, or `kinds=all` — the answer gains one key, **last**:292 `"entities": { "<kind>": [ row, … ] }` (one array per requested kind, in the order above, possibly empty), and `tombstones`293 also contains the tombstones of the requested kinds. An unknown kind → `400 bad_kinds` (the body lists the valid ones).294295Windowing is the one of pages, applied to every list together: each list is `since < rev ≤ head`, oldest first, at most `limit` rows;296when at least one list was cut, `more` is `true`, `cursor` is the lowest last revision among the cut lists, and **every** list is297trimmed to `rev ≤ cursor` — nothing is skipped, nothing is sent twice. Call again with `since=cursor` until `more` is `false`298(`cursor == head`). `since > head` → `reset: true` (restart from 0); when `kinds` was given the answer still carries `"entities"` with **one empty299list per requested kind** (`{"task":[],"canvas":[]}` — same keys as a normal answer, never `{}`).300301**A cursor is only valid for the set of kinds it was obtained with.** A client that starts asking for a kind it did not ask for302before must read that kind from `since=0` (simplest: keep one cursor for `kinds=all` and, on first run of 2.0, restart from 0;303pages already known are simply overwritten with identical data).304305Soft-deleted rows (tasks, databases, database rows, references) stay in the feed as rows with `deletedAt`. **A database follows its306host page**: moving the host page to the trash sets the `deletedAt` of its `database` row to the same instant (new `rev`), restoring307the page puts it back to `null` (new `rev`) — a native client hides / shows the database from that row alone. Its `database_row`s308keep their own `deletedAt` (a row deleted on its own); the rows of a trashed database are hidden through the database. A **tombstone**309`{id, kind, rev, deletedAt}` means the row no longer exists: permanent deletion, including by cascade (purging a database page emits310tombstones for the page, the database, its properties, views and rows; purging a canvas page for the page and the canvas — the311canvas tombstone's `id` is the page id). Re-creating an id removes its tombstone.312313Example — everything created by one small scenario, `kinds=all` (the `pages` array and the long lists are abbreviated here, nothing else):314315```http316GET /api/sync?kinds=all&since=619750&limit=500317```318319```http320HTTP 200321```322323```json324{325 "cursor": 619779,326 "head": 619779,327 "more": false,328 "reset": false,329 "serverTime": "2026-11-19T23:28:08.214Z",330 "workspace": {331 "id": "75bbf9cf-0dad-4ae6-b50c-021e50b12457",332 "name": "Note SPBoucher AI"333 },334 "user": {335 "displayName": "Simon-Pierre Boucher"336 },337 "pages": "[… 6 pages, same shape as 2.x …]",338 "attachments": [339 {340 "id": "725b9723-c31a-40a9-b2ca-6b2f7e48c72f",341 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",342 "filename": "memo.mp3",343 "mime": "audio/mpeg",344 "size": 200,345 "sha256": "295cbb667c2d2380418d4c7576c666c4f1690de2a2433f0e301bd5923377f8ed",346 "pageCount": null,347 "createdAt": "2026-11-19T23:28:08.202Z",348 "deletedAt": null,349 "rev": 619779350 }351 ],352 "tombstones": [],353 "tags": [354 {355 "name": "31999de6",356 "color": "gray"357 },358 {359 "name": "garch",360 "color": "gray"361 },362 {363 "name": "hors-ligne",364 "color": "gray"365 },366 {367 "name": "it-3de28bc7",368 "color": "gray"369 },370 {371 "name": "journal",372 "color": "gray"373 },374 {375 "name": "offline",376 "color": "gray"377 },378 {379 "name": "thèse",380 "color": "gray"381 }382 ],383 "entities": {384 "task": [385 {386 "id": "910c305f-64c6-4d08-b584-28fbeb6fcc29",387 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",388 "blockId": "FKmM69LEHF",389 "title": "Relire la section 2",390 "status": "todo",391 "priority": "high",392 "dueAt": "2026-11-25T12:00:00.000Z",393 "completedAt": null,394 "project": null,395 "createdAt": "2026-11-19T23:28:08.099Z",396 "updatedAt": "2026-11-19T23:28:08.099Z",397 "deletedAt": null,398 "rev": 619757399 },400 "… 1 more"401 ],402 "database": [403 {404 "id": "b7b47434-f9a0-4267-a6fc-433e0ea48b5a",405 "pageId": "db26dee6-75cf-43ef-bfb3-df26094e1661",406 "name": "Exemple · Lectures",407 "description": null,408 "icon": null,409 "isTemplate": false,410 "templateOf": null,411 "createdAt": "2026-11-19T23:28:08.188Z",412 "updatedAt": "2026-11-19T23:28:08.188Z",413 "deletedAt": null,414 "rev": 619773415 }416 ],417 "database_property": [418 {419 "id": "5baddb10-dcbb-46ba-86d5-878db2099eed",420 "databaseId": "b7b47434-f9a0-4267-a6fc-433e0ea48b5a",421 "name": "Name",422 "type": "title",423 "config": {},424 "position": 0,425 "width": 260,426 "createdAt": "2026-11-19T23:28:08.189Z",427 "rev": 619774428 },429 "… 1 more"430 ],431 "database_view": [432 {433 "id": "69eb4f2b-0fff-481c-b994-9a783cdd80fc",434 "databaseId": "b7b47434-f9a0-4267-a6fc-433e0ea48b5a",435 "name": "Table",436 "type": "table",437 "config": {},438 "position": 0,439 "isDefault": true,440 "createdAt": "2026-11-19T23:28:08.189Z",441 "rev": 619775442 }443 ],444 "database_row": [445 {446 "id": "0660e2fc-499b-44b9-86d9-115fc7d257ab",447 "databaseId": "b7b47434-f9a0-4267-a6fc-433e0ea48b5a",448 "pageId": "67a70821-dc3a-4d76-8ade-6602d6cc873c",449 "values": {450 "5baddb10-dcbb-46ba-86d5-878db2099eed": "Engle (1982)",451 "626cdc7c-1ae3-4281-b5ca-a9439fa8d737": 1982452 },453 "position": 1,454 "createdAt": "2026-11-19T23:28:08.197Z",455 "updatedAt": "2026-11-19T23:28:08.197Z",456 "deletedAt": null,457 "rev": 619778458 }459 ],460 "edge": [461 {462 "id": "ec20b9d6-21ba-4294-b3e3-ed9fd4e895af",463 "fromId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",464 "toId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",465 "sourceKind": "page",466 "targetKind": "page",467 "kind": "link",468 "relType": "related",469 "origin": "system",470 "status": "accepted",471 "confidence": null,472 "rationale": null,473 "note": null,474 "model": null,475 "validFrom": null,476 "validTo": null,477 "sourceBlockId": "dSno8OQ_kP",478 "targetBlockId": null,479 "createdAt": "2026-11-19T23:28:08.099Z",480 "updatedAt": "2026-11-19T23:28:08.099Z",481 "decidedAt": null,482 "rev": 619755483 },484 "… 2 more"485 ],486 "reference": [487 {488 "id": "07cd9555-0e33-4006-af38-9005598bdde8",489 "pageId": null,490 "citeKey": "tim1986generalized",491 "entryType": "article",492 "title": "Generalized autoregressive conditional heteroskedasticity",493 "authors": [494 "Bollerslev, Tim"495 ],496 "year": 1986,497 "journal": "Journal of Econometrics",498 "doi": null,499 "url": null,500 "bibtex": "@article{tim1986generalized,\n author = {Bollerslev, Tim},\n title = {Generalized autoregressive conditional heteroskedasticity},\n journal = {Journal of Econometrics},\n year = {1986}\n}",501 "fields": {502 "year": "1986",503 "title": "Generalized autoregressive conditional heteroskedasticity",504 "author": "Bollerslev, Tim",505 "journal": "Journal of Econometrics"506 },507 "verified": "user",508 "attachmentId": null,509 "createdAt": "2026-11-19T23:28:08.087Z",510 "updatedAt": "2026-11-19T23:28:08.087Z",511 "deletedAt": null,512 "rev": 619752513 }514 ],515 "canvas": [516 {517 "id": "495f8abd-a19d-485b-acc1-377b4e43ddd3",518 "pageId": "495f8abd-a19d-485b-acc1-377b4e43ddd3",519 "data": {520 "edges": [521 {522 "id": "e1",523 "to": "n2",524 "from": "n1",525 "kind": "arrow",526 "label": "motive"527 }528 ],529 "nodes": [530 {531 "h": 120,532 "w": 240,533 "x": 0,534 "y": 0,535 "z": 0,536 "id": "n1",537 "kind": "page",538 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1"539 },540 {541 "h": 80,542 "w": 200,543 "x": 320,544 "y": 20,545 "z": 1,546 "id": "n2",547 "kind": "text",548 "text": "Hypothèse H1",549 "color": "#3157d5"550 }551 ],552 "format": "spn-canvas-1",553 "viewport": {554 "x": 0,555 "y": 0,556 "zoom": 1557 }558 },559 "version": 2,560 "createdAt": "2026-11-19T23:28:08.160Z",561 "updatedAt": "2026-11-19T23:28:08.169Z",562 "rev": 619770563 }564 ],565 "concept": [566 {567 "id": "4f1e5a5c-ef5f-4310-b35a-daded50f3f26",568 "name": "Exemple · hétéroscédasticité",569 "description": "Variance non constante",570 "origin": "user",571 "status": "accepted",572 "model": null,573 "createdAt": "2026-11-19T23:28:08.148Z",574 "updatedAt": "2026-11-19T23:28:08.154Z",575 "decidedAt": "2026-11-19T23:28:08.149Z",576 "rev": 619767577 }578 ]579 }580}581```582583The same server, asked without `kinds` right after (2.x shape):584585```http586GET /api/sync?since=619779&limit=5587```588589```http590HTTP 200591```592593```json594{595 "cursor": 619779,596 "head": 619779,597 "more": false,598 "reset": false,599 "serverTime": "2026-11-19T23:28:08.218Z",600 "workspace": {601 "id": "75bbf9cf-0dad-4ae6-b50c-021e50b12457",602 "name": "Note SPBoucher AI"603 },604 "user": {605 "displayName": "Simon-Pierre Boucher"606 },607 "pages": [],608 "attachments": [],609 "tombstones": [],610 "tags": [611 {612 "name": "31999de6",613 "color": "gray"614 },615 {616 "name": "garch",617 "color": "gray"618 },619 {620 "name": "hors-ligne",621 "color": "gray"622 },623 {624 "name": "it-3de28bc7",625 "color": "gray"626 },627 {628 "name": "journal",629 "color": "gray"630 },631 {632 "name": "offline",633 "color": "gray"634 },635 {636 "name": "thèse",637 "color": "gray"638 }639 ]640}641```642643```http644GET /api/sync?kinds=task,unicorn645```646647```http648HTTP 400649```650651```json652{653 "error": "Unknown kind: unicorn",654 "code": "bad_kinds",655 "kinds": [656 "task",657 "database",658 "database_property",659 "database_view",660 "database_row",661 "edge",662 "reference",663 "canvas",664 "concept"665 ]666}667```668669### 3.1 Row shape per kind670671Keys are always present and always in this order. `rev` is last. Types: `uuid`, `string`, `int`, `number`, `bool`, `date` (ISO672string), `json`; `?` = nullable.673674| kind | keys (in order) |675|---|---|676| `task` | `id` uuid · `pageId` uuid? · `blockId` string? (block id of the `taskItem`) · `title` string · `status` `todo\|doing\|done` · `priority` `low\|medium\|high`? · `dueAt` date? · `completedAt` date? · `project` string? · `createdAt` date · `updatedAt` date · `deletedAt` date? · `rev` int |677| `database` | `id` uuid · `pageId` uuid (host page) · `name` string · `description` string? · `icon` string? · `isTemplate` bool · `templateOf` uuid? · `createdAt` · `updatedAt` · `deletedAt` date? · `rev` |678| `database_property` | `id` uuid · `databaseId` uuid · `name` string · `type` (`title text number date checkbox status select multi_select url file relation rollup formula created_time last_edited_time ai`) · `config` json · `position` int · `width` int? · `createdAt` · `rev` |679| `database_view` | `id` uuid · `databaseId` uuid · `name` string · `type` (`table board calendar gallery timeline list`) · `config` json (`filter, sorts, groupBy, hidden, …`) · `position` int · `isDefault` bool · `createdAt` · `rev` |680| `database_row` | `id` uuid · `databaseId` uuid · `pageId` uuid (the row's page, itself in `pages`) · `values` json (keyed by property id; stored values only — relations, rollups and formulas are computed, use `POST /api/query` or the database routes) · `position` number · `createdAt` · `updatedAt` · `deletedAt` date? · `rev` |681| `edge` | `id` uuid · `fromId` uuid · `toId` uuid · `sourceKind` · `targetKind` (`page\|reference\|concept`) · `kind` (`link` document link · `cites` citation · `relation` typed relation · `ai_suggested` 2.x link suggestion) · `relType` (`related`, `supports`, `contradicts`, `extends`, `example_of`, `part_of`, `cites`, `precedes`, `follows`, `about`, `answers`, `duplicates`) · `origin` (`user\|ai\|system`) · `status` (`suggested\|accepted\|rejected`) · `confidence` number? · `rationale` string? · `note` string? · `model` string? · `validFrom` date? · `validTo` date? · `sourceBlockId` string? · `targetBlockId` string? · `createdAt` · `updatedAt` · `decidedAt` date? · `rev` |682| `reference` | `id` uuid · `pageId` uuid? · `citeKey` string · `entryType` string · `title` string · `authors` string[] · `year` int? · `journal` string? · `doi` string? · `url` string? · `bibtex` string? · `fields` json · `verified` (`user\|doi_verified\|ai_suggested`) · `attachmentId` uuid? · `createdAt` · `updatedAt` · `deletedAt` date? · `rev` |683| `canvas` | `id` uuid (= `pageId`) · `pageId` uuid · `data` json (`spn-canvas-1`, §4.8) · `version` int · `createdAt` · `updatedAt` · `rev` |684| `concept` | `id` uuid · `name` string · `description` string? · `origin` (`user\|ai`) · `status` (`suggested\|accepted\|rejected`) · `model` string? · `createdAt` · `updatedAt` · `decidedAt` date? · `rev` |685686The concept ↔ page links are not a kind of their own: a change of a concept's page links bumps the concept's `rev`; read the links687with `GET /api/concepts/<id>`.688689Writes stay on the REST routes; there is no upload through `/api/sync`.690691---692693## 4.2 Tasks694695A task is a row of `tasks` (the source of truth), optionally anchored to a page (`pageId`) and to a `taskItem` of that page696(`blockId`). Task object = the stored row:697698`{ id, workspaceId, pageId, title, status, priority, dueAt, completedAt, project, createdAt, updatedAt, deletedAt, rev, blockId }`699700`status`: `todo | doing | done` (`doing` is used by the research workspace). `completedAt` is set when the status becomes `done`,701cleared otherwise.702703### `POST /api/tasks`704705Body: `id?` uuid · `title` string 1…500 (trimmed) · `dueAt?` \| `due?` — ISO datetime **with offset**, or a bare date706`YYYY-MM-DD`, or null · `priority?` `low|medium|high` (default `medium`) · `project?` string ≤ 100 \| null · `pageId?` uuid \| null ·707`blockId?` string ≤ 64 \| null · `status?` `todo|doing|done` (default `todo`).708709`due` is an alias of `dueAt` (`dueAt` wins when both are sent). **A bare date is stored at 12:00 UTC of that day**, so that it is710the same calendar day in every time zone from UTC−11 to UTC+11; a client that shows only the date reads the UTC date part.711712→ `201` task. With an `id` that already exists: `200`, `x-existing: 1`, the stored task. Errors: `400` (validation),713`400 bad_page` (the page is not a page of the workspace), `409 id_taken`.714715```http716POST /api/tasks717718{719 "id": "d222d0f5-4dd7-42da-a848-c1f7b1dc5d55",720 "title": "Envoyer le plan au directeur",721 "due": "2026-11-21",722 "priority": "medium",723 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1"724}725```726727```http728HTTP 201729```730731```json732{733 "id": "d222d0f5-4dd7-42da-a848-c1f7b1dc5d55",734 "workspaceId": "75bbf9cf-0dad-4ae6-b50c-021e50b12457",735 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",736 "title": "Envoyer le plan au directeur",737 "status": "todo",738 "priority": "medium",739 "dueAt": "2026-11-21T12:00:00.000Z",740 "completedAt": null,741 "project": null,742 "createdAt": "2026-11-19T23:28:08.106Z",743 "updatedAt": "2026-11-19T23:28:08.106Z",744 "deletedAt": null,745 "rev": 619758,746 "blockId": null747}748```749750The same request sent again (lost answer, retry):751752```http753POST /api/tasks754755{756 "id": "d222d0f5-4dd7-42da-a848-c1f7b1dc5d55",757 "title": "Envoyer le plan au directeur"758}759```760761```http762HTTP 200763x-existing: 1764```765766```json767{768 "id": "d222d0f5-4dd7-42da-a848-c1f7b1dc5d55",769 "workspaceId": "75bbf9cf-0dad-4ae6-b50c-021e50b12457",770 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",771 "title": "Envoyer le plan au directeur",772 "status": "todo",773 "priority": "medium",774 "dueAt": "2026-11-21T12:00:00.000Z",775 "completedAt": null,776 "project": null,777 "createdAt": "2026-11-19T23:28:08.106Z",778 "updatedAt": "2026-11-19T23:28:08.106Z",779 "deletedAt": null,780 "rev": 619758,781 "blockId": null782}783```784785```http786POST /api/tasks787788{789 "title": "x",790 "pageId": "9938bc75-88fe-4863-bf9f-63ffa7b2123d"791}792```793794```http795HTTP 400796```797798```json799{800 "error": "Unknown page",801 "code": "bad_page"802}803```804805### `GET /api/tasks`806807`?done=1` (include done tasks) · `?pageId=<uuid>` · `?since=<rev>` (delta: the tasks whose `rev` is greater, **deleted ones808included**, whatever `done`, oldest revision first; for a complete, paged feed use `/api/sync?kinds=task`). → array (≤ 500), open809first, then by `dueAt` (nulls last), then newest. Keys: the81012 keys of 2.x in the same order (`id, title, status, priority, dueAt, completedAt, project, pageId, createdAt, updatedAt, pageTitle,811pageIcon`) followed by `blockId, deletedAt, rev`.812813```http814GET /api/tasks?pageId=a875edb2-ed14-4a41-a91c-8fdf8053f6c1&done=1815```816817```http818HTTP 200819```820821```json822[823 {824 "id": "910c305f-64c6-4d08-b584-28fbeb6fcc29",825 "title": "Relire la section 2",826 "status": "todo",827 "priority": "high",828 "dueAt": "2026-11-25T12:00:00.000Z",829 "completedAt": null,830 "project": null,831 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",832 "createdAt": "2026-11-19T23:28:08.099Z",833 "updatedAt": "2026-11-19T23:28:08.099Z",834 "pageTitle": "Exemple · Revue de littérature",835 "pageIcon": null,836 "blockId": "FKmM69LEHF",837 "deletedAt": null,838 "rev": 619757839 },840 {841 "id": "d222d0f5-4dd7-42da-a848-c1f7b1dc5d55",842 "title": "Envoyer le plan au directeur",843 "status": "done",844 "priority": "medium",845 "dueAt": "2026-11-21T12:00:00.000Z",846 "completedAt": "2026-11-19T23:28:08.113Z",847 "project": null,848 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",849 "createdAt": "2026-11-19T23:28:08.106Z",850 "updatedAt": "2026-11-19T23:28:08.113Z",851 "pageTitle": "Exemple · Revue de littérature",852 "pageIcon": null,853 "blockId": null,854 "deletedAt": null,855 "rev": 619759856 }857]858```859860### `GET /api/tasks/<id>` · `PATCH /api/tasks/<id>` · `DELETE /api/tasks/<id>`861862- `GET` → the task, in any state (a deleted task answers `200` with `deletedAt`). `404 not_found`.863- `PATCH` body: any of `title, status, priority, dueAt | due, project, pageId, blockId` (same types as POST) → the task.864 `404 not_found` (unknown or deleted), `400 bad_page`. Setting `pageId: null` without `blockId` also clears `blockId`.865- `DELETE` → soft delete, `200 {"ok":true,"deleted":true}`; **idempotent**: on an already deleted task866 `200 {"ok":true,"deleted":false}` — and the same for an unknown id (§0.5; it answered `404` before the integration pass).867868```http869PATCH /api/tasks/d222d0f5-4dd7-42da-a848-c1f7b1dc5d55870871{872 "status": "done"873}874```875876```http877HTTP 200878```879880```json881{882 "id": "d222d0f5-4dd7-42da-a848-c1f7b1dc5d55",883 "workspaceId": "75bbf9cf-0dad-4ae6-b50c-021e50b12457",884 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",885 "title": "Envoyer le plan au directeur",886 "status": "done",887 "priority": "medium",888 "dueAt": "2026-11-21T12:00:00.000Z",889 "completedAt": "2026-11-19T23:28:08.113Z",890 "project": null,891 "createdAt": "2026-11-19T23:28:08.106Z",892 "updatedAt": "2026-11-19T23:28:08.113Z",893 "deletedAt": null,894 "rev": 619759,895 "blockId": null896}897```898899```http900DELETE /api/tasks/d222d0f5-4dd7-42da-a848-c1f7b1dc5d55901```902903```http904HTTP 200905```906907```json908{909 "ok": true,910 "deleted": true911}912```913914```http915DELETE /api/tasks/d222d0f5-4dd7-42da-a848-c1f7b1dc5d55916```917918```http919HTTP 200920```921922```json923{924 "ok": true,925 "deleted": false926}927```928929The 2.x forms still work and are unchanged: `PATCH /api/tasks` with `id` in the body, `DELETE /api/tasks?id=` (answers `404` when the930task is already deleted).931932### Tasks and documents933934`taskItem` attrs (SPEC §2): `checked`, `due` (ISO date or datetime), `priority`, `taskId`. When a page is saved:9359361. A `taskItem` whose `taskId` (a UUID chosen by the client) **is not stored yet** creates the task: `title` = the text of the937 item's first block (≤ 500 chars; `Tâche` when empty), `status` from `checked`, `due`, `priority`, `pageId` = the page,938 `blockId` = the item's block id. An offline client therefore needs one write path only: put a fresh UUID in `taskId` and save939 the page. (Creating the task first with `POST /api/tasks {id}` and then saving the page is equivalent.)9402. For a stored task, **only what changed in the document since the previous save of that page** is applied: `checked` ↔ `status`941 (`done` / `todo`), item text → `title`, `due` → `dueAt`, `priority`. The task is (re-)anchored to the item (`pageId`, `blockId`).9423. Removing the item does not delete the task. A `taskId` of another workspace, or of a deleted task, is ignored.943944The other direction is **not** automatic: `PATCH /api/tasks/<id> {status:"done"}` does not rewrite the page (it would bump the page945`version` under an open editor). The client that completes a linked task from a task list should also set `checked` on the item when946it has the page open; if it does not, the task stays `done` (rule 2: a later save of the page that did not touch that item never947reverts it) and the box stays unchecked until someone ticks it. `GET /api/tasks/<id>` gives the anchor:948949```http950GET /api/tasks/910c305f-64c6-4d08-b584-28fbeb6fcc29951```952953```http954HTTP 200955```956957```json958{959 "id": "910c305f-64c6-4d08-b584-28fbeb6fcc29",960 "workspaceId": "75bbf9cf-0dad-4ae6-b50c-021e50b12457",961 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",962 "title": "Relire la section 2",963 "status": "todo",964 "priority": "high",965 "dueAt": "2026-11-25T12:00:00.000Z",966 "completedAt": null,967 "project": null,968 "createdAt": "2026-11-19T23:28:08.099Z",969 "updatedAt": "2026-11-19T23:28:08.099Z",970 "deletedAt": null,971 "rev": 619757,972 "blockId": "FKmM69LEHF"973}974```975976Events: `task.created`, `task.completed`, `task.reopened` (§4.4), with `data.via` = `document | inbox | research | agent` when the task977was not written through `/api/tasks`.978979---980981## 4.3 Knowledge graph 2.0982983### Model984985An **edge** (row of `knowledge_edges`, kind `edge` of the feed) joins two nodes; a node is a page, a reference or a concept986(`sourceKind` / `targetKind`). `kind` is the family, `relType` the meaning:987988| `kind` | Written by | `origin` | Editable |989|---|---|---|---|990| `link` | saving a document (mention, link, `blockRef`, `canvasLink`) | `system` | no (`409 derived_edge`) |991| `cites` | saving a document (`citation`) | `system` | no |992| `relation` | `POST /api/graph/relations` (user), analysis jobs (AI) | `user` \| `ai` | yes |993| `ai_suggested` | 2.x link suggestions (`/api/graph/suggestions`, unchanged) | `ai` | accept / reject only |994995`relType` ∈ `related`, `supports`, `contradicts`, `extends`, `example_of`, `part_of`, `cites`, `precedes`, `follows`, `about`, `answers`, `duplicates`. Several relations of different types may join the same two nodes; (`fromId`, `toId`, `kind`, `relType`)996is unique. Direction matters: `fromId` —relType→ `toId`.997998**Anything created by a model is `status: "suggested"`, `origin: "ai"`, and stays so until the user decides** (`PATCH … {status}`).999`origin` never changes: an accepted AI relation is `origin: "ai", status: "accepted"`. Clients must mark `origin: "ai"` visibly.10001001### `POST /api/graph/relations`10021003Body: `id?` uuid · `fromId` uuid · `toId` uuid · `sourceKind?` · `targetKind?` (`page|reference|concept`, default `page`) · `relType`1004· `note?` string ≤ 2 000 \| null · `validFrom?` · `validTo?` ISO datetime with offset \| null · `sourceBlockId?` · `targetBlockId?`1005string ≤ 64 \| null.10061007→ `201` relation (`origin: "user"`, `status: "accepted"`, `decidedAt` set). Idempotent on `id` (`200`, `x-existing: 1`).1008Errors: `400` validation · `400 bad_node` (a node does not exist, is trashed, or both ends are the same node; `field` = `fromId` or `toId` — `toId` when both ends are the same node) ·1009`400 bad_request` (`validTo` before `validFrom`) · `409 relation_exists` (same from, to, relType; `id` and `status` of the existing one) ·1010`409 id_taken`.10111012```http1013POST /api/graph/relations10141015{1016 "fromId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1017 "toId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1018 "relType": "supports",1019 "note": "Les données appuient la revue",1020 "validFrom": "2026-01-01T00:00:00Z"1021}1022```10231024```http1025HTTP 2011026```10271028```json1029{1030 "id": "72693b47-4de2-4c4c-9f23-e9bf70169092",1031 "fromId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1032 "toId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1033 "sourceKind": "page",1034 "targetKind": "page",1035 "kind": "relation",1036 "relType": "supports",1037 "origin": "user",1038 "status": "accepted",1039 "confidence": null,1040 "rationale": null,1041 "note": "Les données appuient la revue",1042 "model": null,1043 "validFrom": "2026-01-01T00:00:00.000Z",1044 "validTo": null,1045 "sourceBlockId": null,1046 "targetBlockId": null,1047 "createdAt": "2026-11-19T23:28:08.136Z",1048 "updatedAt": "2026-11-19T23:28:08.136Z",1049 "decidedAt": "2026-11-19T23:28:08.136Z",1050 "rev": 619764,1051 "fromTitle": "Exemple · Données",1052 "toTitle": "Exemple · Revue de littérature"1053}1054```10551056```http1057POST /api/graph/relations10581059{1060 "fromId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1061 "toId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1062 "relType": "supports"1063}1064```10651066```http1067HTTP 4091068```10691070```json1071{1072 "error": "This relation already exists",1073 "code": "relation_exists",1074 "id": "72693b47-4de2-4c4c-9f23-e9bf70169092",1075 "status": "accepted"1076}1077```10781079### `GET /api/graph/relations`10801081`?nodeId=<uuid>` (relations touching that node) · `?status=` · `?relType=` · `?origin=` · `?include=cites,ai_suggested,link` (adds1082those families; default: kind `relation` only). → `{ "relations": [ … ] }`, newest first, ≤ 500. Relation object = the `edge` row of1083the feed + `fromTitle`, `toTitle`.10841085```http1086GET /api/graph/relations?nodeId=a875edb2-ed14-4a41-a91c-8fdf8053f6c1&include=cites1087```10881089```http1090HTTP 2001091```10921093```json1094{1095 "relations": [1096 {1097 "id": "72693b47-4de2-4c4c-9f23-e9bf70169092",1098 "fromId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1099 "toId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1100 "sourceKind": "page",1101 "targetKind": "page",1102 "kind": "relation",1103 "relType": "extends",1104 "origin": "user",1105 "status": "accepted",1106 "confidence": null,1107 "rationale": null,1108 "note": null,1109 "model": null,1110 "validFrom": "2026-01-01T00:00:00.000Z",1111 "validTo": null,1112 "sourceBlockId": null,1113 "targetBlockId": null,1114 "createdAt": "2026-11-19T23:28:08.136Z",1115 "updatedAt": "2026-11-19T23:28:08.143Z",1116 "decidedAt": "2026-11-19T23:28:08.136Z",1117 "rev": 619765,1118 "fromTitle": "Exemple · Données",1119 "toTitle": "Exemple · Revue de littérature"1120 },1121 {1122 "id": "af53442d-1347-4ff3-ad2f-d5b6550f9222",1123 "fromId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1124 "toId": "07cd9555-0e33-4006-af38-9005598bdde8",1125 "sourceKind": "page",1126 "targetKind": "reference",1127 "kind": "cites",1128 "relType": "cites",1129 "origin": "system",1130 "status": "accepted",1131 "confidence": null,1132 "rationale": null,1133 "note": null,1134 "model": null,1135 "validFrom": null,1136 "validTo": null,1137 "sourceBlockId": "dSno8OQ_kP",1138 "targetBlockId": null,1139 "createdAt": "2026-11-19T23:28:08.099Z",1140 "updatedAt": "2026-11-19T23:28:08.099Z",1141 "decidedAt": null,1142 "rev": 619756,1143 "fromTitle": "Exemple · Revue de littérature",1144 "toTitle": "Generalized autoregressive conditional heteroskedasticity"1145 }1146 ]1147}1148```11491150### `GET | PATCH | DELETE /api/graph/relations/<id>`11511152- `PATCH` body: any of `status` (`accepted|rejected|suggested`), `relType`, `note`, `validFrom`, `validTo` → relation. A status1153 change sets `decidedAt` (null when put back to `suggested`). `409 derived_edge` for `link` / `cites`; an `ai_suggested` edge accepts1154 only `status` (2.x behaviour kept: accepting it creates the backlink). `409 relation_exists` when the new `relType` collides.1155- `DELETE` → `{"ok":true}`, idempotent (§0.5: an unknown or already deleted id answers the same `200`, and writes no second1156 `relation.removed` event); only kind `relation` (`409 derived_edge` otherwise; a link suggestion is rejected, not deleted).11571158```http1159PATCH /api/graph/relations/72693b47-4de2-4c4c-9f23-e9bf7016909211601161{1162 "relType": "extends",1163 "note": null1164}1165```11661167```http1168HTTP 2001169```11701171```json1172{1173 "id": "72693b47-4de2-4c4c-9f23-e9bf70169092",1174 "fromId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1175 "toId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1176 "sourceKind": "page",1177 "targetKind": "page",1178 "kind": "relation",1179 "relType": "extends",1180 "origin": "user",1181 "status": "accepted",1182 "confidence": null,1183 "rationale": null,1184 "note": null,1185 "model": null,1186 "validFrom": "2026-01-01T00:00:00.000Z",1187 "validTo": null,1188 "sourceBlockId": null,1189 "targetBlockId": null,1190 "createdAt": "2026-11-19T23:28:08.136Z",1191 "updatedAt": "2026-11-19T23:28:08.143Z",1192 "decidedAt": "2026-11-19T23:28:08.136Z",1193 "rev": 619765,1194 "fromTitle": "Exemple · Données",1195 "toTitle": "Exemple · Revue de littérature"1196}1197```11981199### `GET /api/graph?view=…`12001201`view` ∈ `global | local | project | timeline | concepts | documents | references`. **Without `view` the 2.x answer is returned1202unchanged** (`{nodes, edges, center, stats:{pages, edges, suggested}}` with the 2.x node / edge shapes and query parameters).12031204| Parameter | |1205|---|---|1206| `pageId` | required for `local` (the centre) and `project` (the root page of the project) |1207| `depth` | `local` only, 1…4 (default 1) |1208| `from`, `to` | `timeline`: ISO dates (default: the last 90 days) |1209| `suggestions=0` | hide `suggested` edges, concepts and concept links |1210| `hideOrphans=1` | drop nodes without an edge in the view |12111212| View | Pages | Also |1213|---|---|---|1214| `global` | every live page | all references, all concepts |1215| `local` | the page and its neighbours up to `depth` hops | their references, concepts, attachments |1216| `project` | the root page and its sub-pages; pages one hop outside are kept with `external: true` | linked references and concepts |1217| `timeline` | pages created or modified in the range | only edges created in the range (or whose validity interval overlaps it); `range` and `buckets` (per UTC day: pages created, pages modified, edges created) |1218| `concepts` | pages linked to a concept | all concepts; only `about` edges and edges touching a concept |1219| `documents` | pages of the section `documents` | their attachments, linked references |1220| `references` | pages that own or cite a reference | all references; only edges touching a reference |12211222Answer: `{ view, nodes, edges, center, [range, buckets,] stats: {pages, references, concepts, edges, suggested} }`.12231224- **Node**: `id` (the page uuid; `ref:<uuid>`, `concept:<uuid>`, `att:<uuid>` for the other kinds) · `entityId` (the bare uuid) ·1225 `kind` (`page|database|research|row|canvas|reference|concept|attachment`) · `title` · `icon` · `section` · `createdAt` · `updatedAt` ·1226 `databaseId` · `degree`, `in`, `out` (within the view) · `status`, `origin` (concepts) · `external` (project view).1227 Sorted by degree (desc), then title, then id.1228- **Edge**: `id` · `source`, `target` (node ids) · `kind` (`link` · `typed` = a relation of kind `relation` · `ai_suggested` · `cites` ·1229 `reference` = a reference attached to a page · `about` = page → concept · `relation` = a **database** relation, `sub` = property1230 name · `attachment`) · `relType` · `origin` · `status` · `confidence` · `rationale` · `note` · `model` · `validFrom` · `validTo` ·1231 `sourceBlockId` · `targetBlockId` · `createdAt` · `sub`. Edges with a real row carry its uuid as `id` (usable with the relations1232 routes); synthetic ones have ids starting with `e-`.12331234```http1235GET /api/graph?view=local&pageId=a875edb2-ed14-4a41-a91c-8fdf8053f6c1&depth=11236```12371238```http1239HTTP 2001240```12411242```json1243{1244 "view": "local",1245 "nodes": [1246 {1247 "id": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1248 "entityId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1249 "kind": "page",1250 "title": "Exemple · Revue de littérature",1251 "icon": null,1252 "section": "projects",1253 "createdAt": "2026-11-19T23:28:08.098Z",1254 "updatedAt": "2026-11-19T23:28:08.098Z",1255 "databaseId": null,1256 "degree": 5,1257 "in": 1,1258 "out": 41259 },1260 {1261 "id": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1262 "entityId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1263 "kind": "page",1264 "title": "Exemple · Données",1265 "icon": null,1266 "section": "projects",1267 "createdAt": "2026-11-19T23:28:08.091Z",1268 "updatedAt": "2026-11-19T23:28:08.091Z",1269 "databaseId": null,1270 "degree": 2,1271 "in": 1,1272 "out": 11273 },1274 {1275 "id": "concept:4f1e5a5c-ef5f-4310-b35a-daded50f3f26",1276 "entityId": "4f1e5a5c-ef5f-4310-b35a-daded50f3f26",1277 "kind": "concept",1278 "title": "Exemple · hétéroscédasticité",1279 "icon": null,1280 "section": null,1281 "createdAt": "2026-11-19T23:28:08.148Z",1282 "updatedAt": "2026-11-19T23:28:08.154Z",1283 "databaseId": null,1284 "degree": 1,1285 "in": 1,1286 "out": 0,1287 "status": "accepted",1288 "origin": "user"1289 },1290 {1291 "id": "ref:07cd9555-0e33-4006-af38-9005598bdde8",1292 "entityId": "07cd9555-0e33-4006-af38-9005598bdde8",1293 "kind": "reference",1294 "title": "Generalized autoregressive conditional heteroskedasticity",1295 "icon": null,1296 "section": null,1297 "createdAt": "2026-11-19T23:28:08.087Z",1298 "updatedAt": "2026-11-19T23:28:08.087Z",1299 "databaseId": null,1300 "degree": 1,1301 "in": 1,1302 "out": 01303 },1304 {1305 "id": "att:725b9723-c31a-40a9-b2ca-6b2f7e48c72f",1306 "entityId": "725b9723-c31a-40a9-b2ca-6b2f7e48c72f",1307 "kind": "attachment",1308 "title": "memo.mp3",1309 "icon": null,1310 "section": null,1311 "createdAt": "2026-11-19T23:28:08.202Z",1312 "updatedAt": "2026-11-19T23:28:08.202Z",1313 "databaseId": null,1314 "degree": 1,1315 "in": 1,1316 "out": 01317 },1318 {1319 "id": "495f8abd-a19d-485b-acc1-377b4e43ddd3",1320 "entityId": "495f8abd-a19d-485b-acc1-377b4e43ddd3",1321 "kind": "canvas",1322 "title": "Exemple · Carte du projet",1323 "icon": null,1324 "section": "projects",1325 "createdAt": "2026-11-19T23:28:08.160Z",1326 "updatedAt": "2026-11-19T23:28:08.170Z",1327 "databaseId": null,1328 "degree": 0,1329 "in": 0,1330 "out": 01331 }1332 ],1333 "edges": [1334 {1335 "relType": "about",1336 "origin": "user",1337 "status": "accepted",1338 "confidence": null,1339 "rationale": null,1340 "note": null,1341 "model": null,1342 "validFrom": null,1343 "validTo": null,1344 "sourceBlockId": null,1345 "targetBlockId": null,1346 "createdAt": "2026-11-19T23:28:08.148Z",1347 "sub": null,1348 "id": "e-about-a875edb2-ed14-4a41-a91c-8fdf8053f6c1-4f1e5a5c-ef5f-4310-b35a-daded50f3f26",1349 "source": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1350 "target": "concept:4f1e5a5c-ef5f-4310-b35a-daded50f3f26",1351 "kind": "about"1352 },1353 {1354 "id": "ec20b9d6-21ba-4294-b3e3-ed9fd4e895af",1355 "source": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1356 "target": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1357 "kind": "link",1358 "relType": "related",1359 "origin": "system",1360 "status": "accepted",1361 "confidence": null,1362 "rationale": null,1363 "note": null,1364 "model": null,1365 "validFrom": null,1366 "validTo": null,1367 "sourceBlockId": "dSno8OQ_kP",1368 "targetBlockId": null,1369 "createdAt": "2026-11-19T23:28:08.099Z",1370 "sub": null1371 },1372 {1373 "id": "af53442d-1347-4ff3-ad2f-d5b6550f9222",1374 "source": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1375 "target": "ref:07cd9555-0e33-4006-af38-9005598bdde8",1376 "kind": "cites",1377 "relType": "cites",1378 "origin": "system",1379 "status": "accepted",1380 "confidence": null,1381 "rationale": null,1382 "note": null,1383 "model": null,1384 "validFrom": null,1385 "validTo": null,1386 "sourceBlockId": "dSno8OQ_kP",1387 "targetBlockId": null,1388 "createdAt": "2026-11-19T23:28:08.099Z",1389 "sub": null1390 },1391 {1392 "id": "72693b47-4de2-4c4c-9f23-e9bf70169092",1393 "source": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1394 "target": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1395 "kind": "typed",1396 "relType": "extends",1397 "origin": "user",1398 "status": "accepted",1399 "confidence": null,1400 "rationale": null,1401 "note": null,1402 "model": null,1403 "validFrom": "2026-01-01T00:00:00.000Z",1404 "validTo": null,1405 "sourceBlockId": null,1406 "targetBlockId": null,1407 "createdAt": "2026-11-19T23:28:08.136Z",1408 "sub": null1409 },1410 {1411 "relType": "related",1412 "origin": "system",1413 "status": "accepted",1414 "confidence": null,1415 "rationale": null,1416 "note": null,1417 "model": null,1418 "validFrom": null,1419 "validTo": null,1420 "sourceBlockId": null,1421 "targetBlockId": null,1422 "createdAt": "2026-11-19T23:28:08.202Z",1423 "sub": null,1424 "id": "e-att-725b9723-c31a-40a9-b2ca-6b2f7e48c72f",1425 "source": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1426 "target": "att:725b9723-c31a-40a9-b2ca-6b2f7e48c72f",1427 "kind": "attachment"1428 }1429 ],1430 "center": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1431 "stats": {1432 "pages": 3,1433 "references": 1,1434 "concepts": 1,1435 "edges": 5,1436 "suggested": 01437 }1438}1439```14401441```http1442GET /api/graph?view=timeline&from=2026-11-19T22%3A28%3A08.241Z1443```14441445```http1446HTTP 2001447```14481449```json1450{1451 "view": "timeline",1452 "nodes": "[… 9 nodes …]",1453 "edges": "[… 4 edges …]",1454 "center": null,1455 "range": {1456 "from": "2026-11-19T22:28:08.241Z",1457 "to": "2026-11-19T23:28:08.242Z"1458 },1459 "buckets": [1460 {1461 "date": "2026-11-19",1462 "created": 7,1463 "updated": 0,1464 "edges": 41465 }1466 ],1467 "stats": {1468 "pages": 7,1469 "references": 1,1470 "concepts": 1,1471 "edges": 4,1472 "suggested": 01473 }1474}1475```14761477### Concepts — `GET | POST | PATCH /api/concepts`, `GET | PATCH | DELETE /api/concepts/<id>`14781479- `GET /api/concepts?status=accepted|suggested|rejected|all&pageId=` → `{ "concepts": [ … ] }` by name (default `accepted`). Concept1480 object = the feed row + `pages` (accepted links to live pages) + `suggestedPages`.1481- `POST` body: `id?` · `name` 1…120 (whitespace collapsed; unique per workspace, case-insensitive) · `description?` ≤ 2 000 ·1482 `pageIds?` uuid[≤ 200] → `201` concept **with `pageLinks`** (`200` + `x-existing: 1` for a known `id`). `409 concept_exists`1483 (`id`, `status`) · `400 bad_page` (`pageIds`).1484- `GET /api/concepts/<id>` → concept + `pageLinks: [{pageId, title, icon, origin, status, confidence, blockId, model, createdAt}]`.1485- `PATCH /api/concepts/<id>` (or `PATCH /api/concepts` with `id` in the body) — any of: `name`, `description`, `status`1486 (`accepted|rejected|suggested`), `addPages` uuid[], `removePages` uuid[], `pageLinks: [{pageId, status}]` (accept / reject a1487 suggested link) → concept + `pageLinks`. Renaming to the name of another concept → `409 concept_exists` with the `id` and1488 `status` of that concept (same body as on create).1489- `DELETE /api/concepts/<id>` → `{"ok":true}` (its links and the relations touching it go with it); idempotent (§0.5).14901491```http1492POST /api/concepts14931494{1495 "name": "Exemple · hétéroscédasticité",1496 "description": "Variance non constante",1497 "pageIds": [1498 "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1499 "d50d7a0b-4ae3-4740-be08-4e27790f0254"1500 ]1501}1502```15031504```http1505HTTP 2011506```15071508```json1509{1510 "id": "4f1e5a5c-ef5f-4310-b35a-daded50f3f26",1511 "name": "Exemple · hétéroscédasticité",1512 "description": "Variance non constante",1513 "origin": "user",1514 "status": "accepted",1515 "model": null,1516 "createdAt": "2026-11-19T23:28:08.148Z",1517 "updatedAt": "2026-11-19T23:28:08.148Z",1518 "decidedAt": "2026-11-19T23:28:08.149Z",1519 "rev": 619766,1520 "pages": 2,1521 "suggestedPages": 0,1522 "pageLinks": [1523 {1524 "pageId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1525 "title": "Exemple · Données",1526 "icon": null,1527 "origin": "user",1528 "status": "accepted",1529 "confidence": null,1530 "blockId": null,1531 "model": null,1532 "createdAt": "2026-11-19T23:28:08.148Z"1533 },1534 {1535 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1536 "title": "Exemple · Revue de littérature",1537 "icon": null,1538 "origin": "user",1539 "status": "accepted",1540 "confidence": null,1541 "blockId": null,1542 "model": null,1543 "createdAt": "2026-11-19T23:28:08.148Z"1544 }1545 ]1546}1547```15481549```http1550PATCH /api/concepts/4f1e5a5c-ef5f-4310-b35a-daded50f3f2615511552{1553 "removePages": [1554 "d50d7a0b-4ae3-4740-be08-4e27790f0254"1555 ]1556}1557```15581559```http1560HTTP 2001561```15621563```json1564{1565 "id": "4f1e5a5c-ef5f-4310-b35a-daded50f3f26",1566 "name": "Exemple · hétéroscédasticité",1567 "description": "Variance non constante",1568 "origin": "user",1569 "status": "accepted",1570 "model": null,1571 "createdAt": "2026-11-19T23:28:08.148Z",1572 "updatedAt": "2026-11-19T23:28:08.154Z",1573 "decidedAt": "2026-11-19T23:28:08.149Z",1574 "rev": 619767,1575 "pages": 1,1576 "suggestedPages": 0,1577 "pageLinks": [1578 {1579 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1580 "title": "Exemple · Revue de littérature",1581 "icon": null,1582 "origin": "user",1583 "status": "accepted",1584 "confidence": null,1585 "blockId": null,1586 "model": null,1587 "createdAt": "2026-11-19T23:28:08.148Z"1588 }1589 ]1590}1591```15921593### Insights — `GET /api/graph/insights`, `POST /api/graph/insights/run`, `PATCH /api/graph/insights/<id>`15941595`GET /api/graph/insights?status=suggested|accepted|dismissed|all&kind=&limit=<1..100>&intelligence=0`1596→ `{ intelligence, insights, counts }`. **`limit` caps every list of the answer**: each list of `intelligence` *and* `insights`1597(newest first). Without `limit`: 20 per `intelligence` list, 200 `insights`. Out-of-range integers are clamped (`0` → 1, `500` → 100,1598§0.6); `counts` is never capped (totals per status).15991600- `intelligence` — **computed from the data at each call, no model**, same data ⇒ same answer (`null` with `intelligence=0`):1601 `stats`; `centralPages` (PageRank, damping 0.85, over accepted page → page edges and database relations; with `degree`, `in`,1602 `out`); `centralConcepts` (by number of pages); `orphans` (live, non-archived, non-row, non-inbox pages without any accepted edge;1603 ≤ 200); `clusters` (connected components of ≥ 2 pages, large ones split by weighted label propagation; `label` = title of the most1604 central page; `id` is stable for a given member set); `recurringTopics` (tags and accepted concepts carried by ≥ 2 pages);1605 `duplicates` (same normalised title, or same text of ≥ 5 words). `limit` caps each list.1606- `insights` — stored findings awaiting a decision: `{ id, kind, status, title, detail, data, origin, model, createdAt, decidedAt }`,1607 `kind` ∈ `contradiction | open_question | cluster | recurring_topic | duplicate`, `origin` `system` (deterministic) or `ai`,1608 `data.pageIds` always present, `data.blockIds` when passages are cited (`contradiction`: also `data.a`, `data.b` =1609 `{pageId, blockId}` and `data.confidence`; `open_question`: `data.source`).1610- `counts` — `{suggested, accepted, dismissed}`.16111612`POST /api/graph/insights/run` — body (required, may be `{}`): `mode?` `all | deterministic | ai` (default `all`) · `pageIds?`1613uuid[≤ 40] · `limit?` 2…40 (pages sent to the model, default 24, most recently edited).1614The deterministic part (clusters of ≥ 3 pages, recurring topics, duplicates) is done in the request; the AI part (contradictions,1615open questions, concept suggestions) is **one job** on the queue `graph-insights` (at most one per workspace per 5 minutes, never1616retried automatically). → `202` when a job was queued, `200` otherwise:1617`{ mode, deterministic: {created, considered} | null, queued, jobId, [reason] }`. Results appear in `GET /api/graph/insights` as1618`suggested`; a finding that cites a page or a block that does not exist is dropped by the server and never stored; a finding already1619known (same pages / passages) is not stored twice; a dismissed one does not come back.16201621```http1622POST /api/graph/insights/run16231624{1625 "mode": "deterministic"1626}1627```16281629```http1630HTTP 2001631```16321633```json1634{1635 "mode": "deterministic",1636 "deterministic": {1637 "created": 1,1638 "considered": 11639 },1640 "queued": false,1641 "jobId": null1642}1643```16441645```http1646GET /api/graph/insights?limit=51647```16481649```http1650HTTP 2001651```16521653```json1654{1655 "intelligence": {1656 "computedAt": "2026-11-19T23:28:08.251Z",1657 "stats": {1658 "pages": 6,1659 "edges": 2,1660 "orphans": 4,1661 "clusters": 1,1662 "concepts": 1,1663 "tags": 21664 },1665 "centralPages": [1666 {1667 "id": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1668 "title": "Exemple · Revue de littérature",1669 "icon": null,1670 "degree": 1,1671 "in": 1,1672 "out": 1,1673 "pagerank": 0.3846151674 },1675 {1676 "id": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1677 "title": "Exemple · Données",1678 "icon": null,1679 "degree": 1,1680 "in": 1,1681 "out": 1,1682 "pagerank": 0.3846151683 }1684 ],1685 "centralConcepts": [1686 {1687 "id": "4f1e5a5c-ef5f-4310-b35a-daded50f3f26",1688 "name": "Exemple · hétéroscédasticité",1689 "status": "accepted",1690 "origin": "user",1691 "pages": 11692 }1693 ],1694 "orphans": [1695 {1696 "id": "db26dee6-75cf-43ef-bfb3-df26094e1661",1697 "title": "Exemple · Lectures",1698 "icon": null,1699 "section": "databases",1700 "updatedAt": "2026-11-19T23:28:08.182Z"1701 },1702 {1703 "id": "495f8abd-a19d-485b-acc1-377b4e43ddd3",1704 "title": "Exemple · Carte du projet",1705 "icon": null,1706 "section": "projects",1707 "updatedAt": "2026-11-19T23:28:08.170Z"1708 },1709 {1710 "id": "20709b78-b934-40aa-8fa9-8698e5039d5a",1711 "title": "Exemple · Thèse",1712 "icon": null,1713 "section": "projects",1714 "updatedAt": "2026-11-19T23:28:08.078Z"1715 },1716 {1717 "id": "acbd524f-4899-4964-8ac7-102ad893d29c",1718 "title": "it-f0ea9fbc ia",1719 "icon": null,1720 "section": "notes",1721 "updatedAt": "2026-11-19T23:16:44.139Z"1722 }1723 ],1724 "clusters": [1725 {1726 "id": "561133d57f20a5a5083a5c83a3e68803e3a6a7ba",1727 "size": 2,1728 "label": "Exemple · Revue de littérature",1729 "pageIds": [1730 "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1731 "d50d7a0b-4ae3-4740-be08-4e27790f0254"1732 ],1733 "top": [1734 {1735 "id": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1736 "title": "Exemple · Revue de littérature",1737 "icon": null1738 },1739 {1740 "id": "d50d7a0b-4ae3-4740-be08-4e27790f0254",1741 "title": "Exemple · Données",1742 "icon": null1743 }1744 ]1745 }1746 ],1747 "recurringTopics": [1748 {1749 "kind": "tag",1750 "id": "e31f9c2e-00f0-4218-8e19-bb8004d5b7a4",1751 "name": "thèse",1752 "pages": 2,1753 "pageIds": [1754 "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1755 "d50d7a0b-4ae3-4740-be08-4e27790f0254"1756 ],1757 "lastActivityAt": "2026-11-19T23:28:08.098Z"1758 }1759 ],1760 "duplicates": []1761 },1762 "insights": [1763 {1764 "id": "75c406e6-70d3-417d-b5bd-fca0c6725c68",1765 "kind": "recurring_topic",1766 "status": "suggested",1767 "title": "#thèse",1768 "detail": "2 pages",1769 "data": {1770 "name": "thèse",1771 "pages": 2,1772 "pageIds": [1773 "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1774 "d50d7a0b-4ae3-4740-be08-4e27790f0254"1775 ],1776 "topicId": "e31f9c2e-00f0-4218-8e19-bb8004d5b7a4",1777 "topicKind": "tag"1778 },1779 "origin": "system",1780 "model": null,1781 "createdAt": "2026-11-19T23:28:08.248Z",1782 "decidedAt": null1783 },1784 {1785 "id": "6249494f-afa7-4029-a1b4-26a604eb7fe0",1786 "kind": "recurring_topic",1787 "status": "suggested",1788 "title": "#nx-graph-topic",1789 "detail": "2 pages",1790 "data": {1791 "name": "nx-graph-topic",1792 "pages": 2,1793 "pageIds": [1794 "3ab2d619-c3f1-4274-87f6-b0d666424b3d",1795 "5833ebff-edc1-43d9-8309-3533cc2acd2e"1796 ],1797 "topicId": "c13c32b8-0311-4c67-be02-c788cf810032",1798 "topicKind": "tag"1799 },1800 "origin": "system",1801 "model": null,1802 "createdAt": "2026-11-19T23:27:36.989Z",1803 "decidedAt": null1804 },1805 {1806 "id": "efd6da23-e1d9-47eb-8bb9-28bc58ab3a54",1807 "kind": "recurring_topic",1808 "status": "suggested",1809 "title": "#nx-graph-topic",1810 "detail": "2 pages",1811 "data": {1812 "name": "nx-graph-topic",1813 "pages": 2,1814 "pageIds": [1815 "ca5be17e-9cd6-4676-9268-b01806c601ec",1816 "e01f4f8e-879f-4820-bed2-fc013dc72144"1817 ],1818 "topicId": "86f43c98-104d-4eea-9fea-9a891f156202",1819 "topicKind": "tag"1820 },1821 "origin": "system",1822 "model": null,1823 "createdAt": "2026-11-19T22:29:22.688Z",1824 "decidedAt": null1825 },1826 {1827 "id": "c9ca0a42-5757-4f94-93e7-35f0fafbffa7",1828 "kind": "recurring_topic",1829 "status": "suggested",1830 "title": "#nx-graph-topic",1831 "detail": "2 pages",1832 "data": {1833 "name": "nx-graph-topic",1834 "pages": 2,1835 "pageIds": [1836 "107747fb-333f-43b7-bf66-fab9a1c866f7",1837 "247b045d-6979-48ef-97b4-f6c935db42fb"1838 ],1839 "topicId": "45573363-dbf8-4ae1-8a4a-7d0b1a39e668",1840 "topicKind": "tag"1841 },1842 "origin": "system",1843 "model": null,1844 "createdAt": "2026-11-19T22:26:59.763Z",1845 "decidedAt": null1846 }1847 ],1848 "counts": {1849 "suggested": 4,1850 "accepted": 0,1851 "dismissed": 01852 }1853}1854```18551856`PATCH /api/graph/insights/<id>` `{ "status": "accepted" | "dismissed" | "suggested" }` → the insight + `relationId`. Accepting a1857`contradiction` between two pages records the relation `contradicts` (`origin: "ai"`, accepted by that decision) and returns its id.18581859```http1860PATCH /api/graph/insights/75c406e6-70d3-417d-b5bd-fca0c6725c6818611862{1863 "status": "dismissed"1864}1865```18661867```http1868HTTP 2001869```18701871```json1872{1873 "id": "75c406e6-70d3-417d-b5bd-fca0c6725c68",1874 "kind": "recurring_topic",1875 "status": "dismissed",1876 "title": "#thèse",1877 "detail": "2 pages",1878 "data": {1879 "name": "thèse",1880 "pages": 2,1881 "pageIds": [1882 "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",1883 "d50d7a0b-4ae3-4740-be08-4e27790f0254"1884 ],1885 "topicId": "e31f9c2e-00f0-4218-8e19-bb8004d5b7a4",1886 "topicKind": "tag"1887 },1888 "origin": "system",1889 "model": null,1890 "createdAt": "2026-11-19T23:28:08.248Z",1891 "decidedAt": "2026-11-19T23:28:08.254Z",1892 "relationId": null1893}1894```18951896<!-- AI-WORKSTREAM --> The AI job's provider call goes through `routedInsightModel` in `src/lib/graph/insights.ts` (existing router,1897task `reason`, strict JSON schema `INSIGHT_SCHEMA`). The automated suites test it with an injected model; one real run through the live worker (`claude-opus-5-5`, 18 s, 0.043 USD:1898the seeded contradiction found, every cited page and block existing) is recorded in `docs/next/AI-LIVE-VERIFICATION.md`.18991900### Constellation — `GET /api/graph/constellation` <!-- NEXT-K (knowledge screens workstream) -->19011902Feature flag `constellation`. The « Thought Constellation » (Labs): notes placed by meaning. `?refresh=1` recomputes the projection.1903**No model is called**: the positions come from the embeddings the search index already stores.19041905→ `{ model, computedAt, cached, signature, explained, stats, points, clusters, links, projects, tags }`19061907- A point is a live, non-archived page outside the inbox that has at least one embedded chunk. Its vector is the mean of its chunk1908 embeddings (pgvector `avg`); the cloud is projected to the plane by a **deterministic PCA** (power iteration with a fixed start1909 vector, each axis signed so that its largest loading is positive, coordinates scaled together into [-1, 1], `y` up). The same1910 embeddings always give the same map; near-identical notes are fanned out on a small spiral so every star stays reachable.1911- `explained` — share of the variance carried by each of the two axes (their sum says how much the flat map can be trusted).1912- The projection is cached per workspace (settings row) and recomputed only when `signature` changes1913 (`<embedding model>:<embeddings>:<embedded pages>:<date of the latest embedding>`); `cached` says which happened. Titles, tags,1914 projects and links are read at each call.1915- `stats`: `pages` (live pages) · `embedded` (pages with vectors) · `shown` (points) · `links` · `truncated` (more than 5 000 embedded1916 pages: the 5 000 most recently edited are shown). **`embedded: 0` ⇒ `points: []`**: clients show an empty state, never a made-up layout.1917- `points[]`: `id` · `title` · `icon` · `type` · `section` · `x`, `y` · `cluster` (index in `clusters`) · `projectId` (top-most ancestor1918 in the section `projects`, or itself; null outside a project) · `tags` (names) · `updatedAt` · `words` · `degree` (links below).1919- `clusters[]` (deterministic k-means in the plane, about √(n/2) clusters, at most 18): `id` · `x`, `y` · `r` (distance to the farthest1920 member) · `size` · `label` (title of the page closest to the centre) · `topTags`.1921- `links[]`: accepted page ↔ page edges between two points, one per pair: `id` · `source` · `target` · `kind` · `relType` · `origin`.1922- `projects[]` `{id, title, icon, pages}` and `tags[]` `{name, color, pages}` — for colouring, most frequent first.19231924Measured on a synthetic workspace of 4 999 embedded pages (1536-d vectors): first computation 2.1 s, cached answer 0.12 s.19251926(Real answer of the scratch instance `note_next_k_dev`; `points`, `clusters`, `links`, `projects` and `tags` cut to their first items.)19271928```http1929GET /api/graph/constellation1930```19311932```http1933HTTP 2001934```19351936```json1937{1938 "model": "text-embedding-3-small",1939 "computedAt": "2026-11-19T20:16:34.434Z",1940 "cached": false,1941 "signature": "text-embedding-3-small:13:9:2026-11-19T19:32:57.895Z",1942 "explained": [1943 0.28118,1944 0.172061945 ],1946 "stats": {1947 "pages": 9,1948 "embedded": 9,1949 "shown": 9,1950 "links": 6,1951 "truncated": false1952 },1953 "points": [1954 {1955 "id": "10563baa-0631-4f9a-a9e7-14390f56a724",1956 "title": "Demo · Mortgage renewal",1957 "icon": "🏦",1958 "type": "page",1959 "section": "projects",1960 "x": -0.25529,1961 "y": 0.00405,1962 "cluster": 0,1963 "projectId": "10563baa-0631-4f9a-a9e7-14390f56a724",1964 "tags": [],1965 "updatedAt": "2026-11-19T19:32:36.705Z",1966 "words": 27,1967 "degree": 21968 },1969 {1970 "id": "115dfe11-7419-452c-a041-647f3e89d029",1971 "title": "Demo · Reading notes — fixed vs variable",1972 "icon": "📚",1973 "type": "page",1974 "section": "documents",1975 "x": -0.49232,1976 "y": 0.07143,1977 "cluster": 0,1978 "projectId": null,1979 "tags": [],1980 "updatedAt": "2026-11-19T19:32:36.825Z",1981 "words": 28,1982 "degree": 11983 },1984 {1985 "id": "3cba9d2f-f1e9-4ed6-9156-550614756f88",1986 "title": "Demo · Household budget",1987 "icon": "🧮",1988 "type": "page",1989 "section": "notes",1990 "x": -0.25166,1991 "y": -0.01337,1992 "cluster": 0,1993 "projectId": null,1994 "tags": [],1995 "updatedAt": "2026-11-19T19:32:36.815Z",1996 "words": 15,1997 "degree": 11998 }1999 ],2000 "clusters": [2001 {2002 "id": 0,2003 "x": -0.125,2004 "y": -0.09891,2005 "r": 0.95743,2006 "size": 8,2007 "label": "Demo · Household budget",2008 "topTags": [2009 "finance",2010 "mortgage"2011 ]2012 },2013 {2014 "id": 1,2015 "x": 1,2016 "y": 0.79128,2017 "r": 0,2018 "size": 1,2019 "label": "Demo · Garden ideas",2020 "topTags": []2021 }2022 ],2023 "links": [2024 {2025 "id": "6123d6c5-501c-4b0e-8f61-05f6e8448a2b",2026 "source": "57d7caa6-c60f-41d7-bab6-b03e4f8fcdb6",2027 "target": "ff05a3e9-4d72-4b05-bcdb-04100a82f838",2028 "kind": "link",2029 "relType": "related",2030 "origin": "system"2031 },2032 {2033 "id": "1671f387-7b14-4dab-ba89-5959c5af4960",2034 "source": "5be0006b-6515-4c22-bfd5-86295f3706fe",2035 "target": "57d7caa6-c60f-41d7-bab6-b03e4f8fcdb6",2036 "kind": "link",2037 "relType": "related",2038 "origin": "system"2039 },2040 {2041 "id": "b7274800-7b41-4fee-b7d6-5324665ffcaf",2042 "source": "5be0006b-6515-4c22-bfd5-86295f3706fe",2043 "target": "ff05a3e9-4d72-4b05-bcdb-04100a82f838",2044 "kind": "link",2045 "relType": "related",2046 "origin": "system"2047 }2048 ],2049 "projects": [2050 {2051 "id": "10563baa-0631-4f9a-a9e7-14390f56a724",2052 "title": "Demo · Mortgage renewal",2053 "icon": "🏦",2054 "pages": 32055 }2056 ],2057 "tags": [2058 {2059 "name": "finance",2060 "color": "gray",2061 "pages": 32062 },2063 {2064 "name": "mortgage",2065 "color": "gray",2066 "pages": 22067 }2068 ]2069}2070```20712072---20732074## 4.4 Events journal and time machine20752076### Events20772078An event: `{ id, at, kind, pageId, pageTitle, pageIcon, entityKind, entityId, actor, device, summary, data }`.2079`actor` ∈ `user | agent | ai | system`; `device` is the session's device label (null for jobs); `pageTitle` / `pageIcon` are the2080**current** ones (null when the page was purged); `summary` is the title or the name at the time of the event.20812082Kinds (30): `page.created`, `page.renamed`, `page.edited`, `page.moved`, `page.archived`, `page.unarchived`, `page.trashed`, `page.restored`, `page.purged`, `page.version`, `tag.added`, `tag.removed`, `link.added`, `link.removed`, `relation.created`, `relation.accepted`, `relation.rejected`, `relation.removed`, `reference.added`, `reference.linked`, `attachment.added`, `task.created`, `task.completed`, `task.reopened`, `capture.created`, `capture.filed`, `ai.applied`, `agent.applied`, `decision.recorded`, `canvas.edited`.20832084| kind | written when | `entityKind` / `entityId` | `data` |2085|---|---|---|---|2086| `page.created` | a page is created (any path: API, capture, import, database row, agent) | page | `section, type, [parentId, databaseId, via:"import"], [backfilled:true]` |2087| `page.renamed` | the title changes | page | `from, to` |2088| `page.edited` | the content changes — **coalesced: at most one per page per 10 minutes** | page | `version, wordCount` (of the save that opened the window) |2089| `page.moved` | `parentId` or `section` changes | page | `from:{parentId, section}, to:{…}` |2090| `page.archived` / `page.unarchived` | | page | — |2091| `page.trashed` / `page.restored` | on the page given to the route (not on each sub-page) | page | `count` (pages affected) |2092| `page.purged` | one per page permanently deleted | page | `attachments` |2093| `page.version` | a history entry is taken | `page_version` / entry id | `version, reason, [unapplied:true], [backfilled:true]` |2094| `tag.added` / `tag.removed` | | `tag` / tag name | `tag` |2095| `link.added` / `link.removed` | a page → page reference appears in / disappears from a document | page / target id | `toId, [toTitle, sourceBlockId, targetBlockId]` |2096| `relation.created` | a user creates a typed relation | `edge` / id | `relationId, relType, origin, fromId, toId, sourceKind, targetKind, fromTitle, toTitle, [model]` |2097| `relation.accepted` / `relation.rejected` | a decision on a suggested relation or link suggestion | `edge` | same |2098| `relation.removed` | a relation is deleted | `edge` | same |2099| `reference.added` | a reference is created | `reference` / id | `citeKey, verified, [doi]` |2100| `reference.linked` | a reference is attached to a page, or cited for the first time in a page | `reference` | `referenceId, citeKey, title, via:"page"\|"citation", [sourceBlockId]` |2101| `attachment.added` | upload | `attachment` / id | `mime, size` |2102| `task.created` / `task.completed` / `task.reopened` | | `task` / id | `[priority, dueAt, blockId, via]` |2103| `capture.created` | `POST /api/capture` | page | `kind, attachments` |2104| `capture.filed` | inbox triage | page | `action, [actionId, section]` |2105| `ai.applied` | an `aiBlock` appears in a saved document | `block` / block id | `blockId, model, action` |2106| `agent.applied` | an agent proposal is approved and applied (`actor: "agent"`) | `execution` / id | `executionId, agent, change, kind, model, …` |2107| `decision.recorded` | a `callout` of kind `decision` appears in a saved document; `summary` = its text | `block` / block id | `blockId` |2108| `canvas.edited` | a canvas is saved — coalesced like `page.edited` | `canvas` / page id | `version, nodes, edges` |21092110Events are written by the mutation, in its transaction: a refused save (409) or a failed one leaves no event. **Nothing is2111back-filled** except `page.created` (from `pages.created_at`) and `page.version` (from the existing history), both with2112`data.backfilled = true` and `actor: "system"`; everything else exists only from the deployment of 3.0 on (`journalSince` of the time2113machine gives the date of the first real event).21142115### `GET /api/events`21162117`?pageId=<uuid>` | `?projectId=<uuid>` (a page and all its sub-pages, trashed ones included; not both) · `?from=` · `?to=` ISO dates2118· `?kinds=a,b` (exact kinds or families: `page.*`, `task.*`) · `?limit=<1..200, default 50>` · `?cursor=<opaque>`.2119→ `{ "events": [ … ], "nextCursor": "<opaque>" | null }`, newest first. Pass `nextCursor` back as `cursor` until it is null; the2120cursor is a position in (time, id) order, so events that arrive while paging never shift a page already read.2121Errors: `400 bad_kinds` · `400 bad_cursor` · `400 bad_request` · `404` (unknown `projectId`).21222123```http2124GET /api/events?pageId=a875edb2-ed14-4a41-a91c-8fdf8053f6c1&limit=42125```21262127```http2128HTTP 2002129```21302131```json2132{2133 "events": [2134 {2135 "id": "fd9237fa-a8b8-4405-a1d3-3f6ca79f1a5f",2136 "at": "2026-11-19T23:28:08.202Z",2137 "kind": "attachment.added",2138 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2139 "pageTitle": "Exemple · Revue de littérature",2140 "pageIcon": null,2141 "entityKind": "attachment",2142 "entityId": "725b9723-c31a-40a9-b2ca-6b2f7e48c72f",2143 "actor": "user",2144 "device": "SP Notes · Mac",2145 "summary": "memo.mp3",2146 "data": {2147 "mime": "audio/mpeg",2148 "size": 2002149 }2150 },2151 {2152 "id": "fb4914b5-9ce7-438a-b109-822aba12733b",2153 "at": "2026-11-19T23:28:08.128Z",2154 "kind": "tag.added",2155 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2156 "pageTitle": "Exemple · Revue de littérature",2157 "pageIcon": null,2158 "entityKind": "tag",2159 "entityId": "thèse",2160 "actor": "user",2161 "device": "SP Notes · Mac",2162 "summary": "thèse",2163 "data": {2164 "tag": "thèse"2165 }2166 },2167 {2168 "id": "90d53386-892b-498d-a28d-4d7a5135a017",2169 "at": "2026-11-19T23:28:08.128Z",2170 "kind": "tag.added",2171 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2172 "pageTitle": "Exemple · Revue de littérature",2173 "pageIcon": null,2174 "entityKind": "tag",2175 "entityId": "garch",2176 "actor": "user",2177 "device": "SP Notes · Mac",2178 "summary": "garch",2179 "data": {2180 "tag": "garch"2181 }2182 },2183 {2184 "id": "be080627-00cc-44f7-9fa2-8d8bf66c52bd",2185 "at": "2026-11-19T23:28:08.112Z",2186 "kind": "task.completed",2187 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2188 "pageTitle": "Exemple · Revue de littérature",2189 "pageIcon": null,2190 "entityKind": "task",2191 "entityId": "d222d0f5-4dd7-42da-a848-c1f7b1dc5d55",2192 "actor": "user",2193 "device": "SP Notes · Mac",2194 "summary": "Envoyer le plan au directeur",2195 "data": {}2196 }2197 ],2198 "nextCursor": "MjAyNi0xMS0xOVQyMzoyODowOC4xMTJafGJlMDgwNjI3LTAwY2MtNDRmNy05ZmEyLThkOGJmNjZjNTJiZA"2199}2200```22012202```http2203GET /api/events?projectId=20709b78-b934-40aa-8fa9-8698e5039d5a&kinds=relation.*,task.*&limit=32204```22052206```http2207HTTP 2002208```22092210```json2211{2212 "events": [2213 {2214 "id": "d4756e3a-64c6-4e3a-8c89-4b244164479f",2215 "at": "2026-11-19T23:28:08.136Z",2216 "kind": "relation.created",2217 "pageId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",2218 "pageTitle": "Exemple · Données",2219 "pageIcon": null,2220 "entityKind": "edge",2221 "entityId": "72693b47-4de2-4c4c-9f23-e9bf70169092",2222 "actor": "user",2223 "device": "SP Notes · Mac",2224 "summary": "Exemple · Données — supports → Exemple · Revue de littérature",2225 "data": {2226 "toId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2227 "fromId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",2228 "origin": "user",2229 "relType": "supports",2230 "toTitle": "Exemple · Revue de littérature",2231 "fromTitle": "Exemple · Données",2232 "relationId": "72693b47-4de2-4c4c-9f23-e9bf70169092",2233 "sourceKind": "page",2234 "targetKind": "page"2235 }2236 },2237 {2238 "id": "be080627-00cc-44f7-9fa2-8d8bf66c52bd",2239 "at": "2026-11-19T23:28:08.112Z",2240 "kind": "task.completed",2241 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2242 "pageTitle": "Exemple · Revue de littérature",2243 "pageIcon": null,2244 "entityKind": "task",2245 "entityId": "d222d0f5-4dd7-42da-a848-c1f7b1dc5d55",2246 "actor": "user",2247 "device": "SP Notes · Mac",2248 "summary": "Envoyer le plan au directeur",2249 "data": {}2250 },2251 {2252 "id": "6888a8d6-af97-4e6d-976f-a61baba0346d",2253 "at": "2026-11-19T23:28:08.106Z",2254 "kind": "task.created",2255 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2256 "pageTitle": "Exemple · Revue de littérature",2257 "pageIcon": null,2258 "entityKind": "task",2259 "entityId": "d222d0f5-4dd7-42da-a848-c1f7b1dc5d55",2260 "actor": "user",2261 "device": "SP Notes · Mac",2262 "summary": "Envoyer le plan au directeur",2263 "data": {2264 "dueAt": "2026-11-21T12:00:00.000Z",2265 "priority": "medium"2266 }2267 }2268 ],2269 "nextCursor": "MjAyNi0xMS0xOVQyMzoyODowOC4xMDZafDY4ODhhOGQ2LWFmOTctNGU2ZC05NzZmLWE2MWJhYmEwMzQ2ZA"2270}2271```22722273### `GET /api/timemachine`22742275`?at=<ISO date>` (required) and exactly one of `?pageId=<uuid>` | `?projectId=<uuid>` · `?content=0|1` (default: content included for2276`pageId`, omitted for `projectId`).22772278→ `{ at, scope, pages, relations, references, removedSince, journalSince }`.22792280`pages[]` (the root first, then by creation date): `id` · `title` (at that date) · `icon` · `section` · `parentId` (current) ·2281`existed` · `trashedAt` (when it was in the trash at that date) · `source` · `exact` · `version` · `versionId` · `versionAt` ·2282`wordCount` · `currentTitle` · `currentVersion` · `changedSince` · `content`, `properties` (when included).22832284| `source` | Meaning | `exact` |2285|---|---|---|2286| `current` | the page has not changed since `at`: its present state is the state at that date | `true` |2287| `version` | the most recent history entry taken at or before `at` (SPEC: nearest version ≤ at). History entries are taken every 10 minutes / 20 saves: edits between that entry and `at` are not in it | `false` |2288| `version_after` | no entry at or before `at`: the first one taken after it, i.e. the page as it was just before that later save (exact when nothing was saved in between — the usual case right after creation — but the server cannot prove it) | `false` |2289| `none` | **the page did not exist yet** (`existed: false`: created after `at` — `version`, `versionId`, `versionAt`, `wordCount` are `null`, no `content`), or it existed and no history covers that date (`existed: true`) | `false` (there is no state to be exact about; it said `true` for a page not yet created before the integration pass) |22902291`relations[]`: edges touching the pages of the scope that were created by `at`, accepted by `at`, and valid at `at` when they carry a2292validity interval (edge keys + `fromTitle`, `toTitle`). `references[]`: references created by `at` (and not deleted by then) attached2293to or cited by those pages. `removedSince[]`: `link.removed` / `relation.removed` events after `at` on those pages — what existed2294then and is gone now, as far as the journal knows.22952296To bring a page back to a listed state: **`POST /api/pages/<id>/versions/<versionId>/restore`** — optional body2297`{ "baseVersion": <currentVersion> }` → `200 {"ok":true,"version":<new>,"restored":<version number>}`. `<versionId>` is the entry id2298(or its version number). The current state is saved in the history first (same path as the 2.x `POST /api/pages/<id>/versions2299{version}`, which still exists). With `baseVersion`, `409 conflict` when the page changed meanwhile. `404` unknown entry, `400`2300malformed.23012302```http2303GET /api/timemachine?at=2026-11-19T23%3A28%3A08.226Z&pageId=d50d7a0b-4ae3-4740-be08-4e27790f02542304```23052306```http2307HTTP 2002308```23092310```json2311{2312 "at": "2026-11-19T23:28:08.226Z",2313 "scope": {2314 "pageId": "d50d7a0b-4ae3-4740-be08-4e27790f0254"2315 },2316 "pages": [2317 {2318 "id": "d50d7a0b-4ae3-4740-be08-4e27790f0254",2319 "icon": null,2320 "section": "projects",2321 "parentId": "20709b78-b934-40aa-8fa9-8698e5039d5a",2322 "trashedAt": null,2323 "currentTitle": "Exemple · Données",2324 "currentVersion": 1,2325 "title": "Exemple · Données",2326 "existed": true,2327 "source": "current",2328 "exact": true,2329 "version": 1,2330 "versionId": null,2331 "versionAt": "2026-11-19T23:28:08.091Z",2332 "wordCount": 6,2333 "changedSince": false,2334 "content": {2335 "type": "doc",2336 "content": [2337 {2338 "type": "paragraph",2339 "attrs": {2340 "id": "7ta0gBIZrD"2341 },2342 "content": [2343 {2344 "text": "Les séries couvrent 2010 à 2025.",2345 "type": "text"2346 }2347 ]2348 }2349 ]2350 },2351 "properties": {}2352 }2353 ],2354 "relations": [2355 {2356 "id": "ec20b9d6-21ba-4294-b3e3-ed9fd4e895af",2357 "fromId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2358 "toId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",2359 "sourceKind": "page",2360 "targetKind": "page",2361 "kind": "link",2362 "relType": "related",2363 "origin": "system",2364 "note": null,2365 "validFrom": null,2366 "validTo": null,2367 "sourceBlockId": "dSno8OQ_kP",2368 "targetBlockId": null,2369 "createdAt": "2026-11-19T23:28:08.099Z",2370 "fromTitle": "Exemple · Revue de littérature",2371 "toTitle": "Exemple · Données"2372 },2373 {2374 "id": "72693b47-4de2-4c4c-9f23-e9bf70169092",2375 "fromId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",2376 "toId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2377 "sourceKind": "page",2378 "targetKind": "page",2379 "kind": "relation",2380 "relType": "extends",2381 "origin": "user",2382 "note": null,2383 "validFrom": "2026-01-01T00:00:00.000Z",2384 "validTo": null,2385 "sourceBlockId": null,2386 "targetBlockId": null,2387 "createdAt": "2026-11-19T23:28:08.136Z",2388 "fromTitle": "Exemple · Données",2389 "toTitle": "Exemple · Revue de littérature"2390 }2391 ],2392 "references": [],2393 "removedSince": [],2394 "journalSince": "2026-11-19T21:42:40.365Z"2395}2396```23972398```http2399GET /api/timemachine?at=2026-11-19T23%3A28%3A08.231Z&projectId=20709b78-b934-40aa-8fa9-8698e5039d5a2400```24012402```http2403HTTP 2002404```24052406```json2407{2408 "at": "2026-11-19T23:28:08.231Z",2409 "scope": {2410 "projectId": "20709b78-b934-40aa-8fa9-8698e5039d5a"2411 },2412 "pages": [2413 {2414 "id": "20709b78-b934-40aa-8fa9-8698e5039d5a",2415 "icon": null,2416 "section": "projects",2417 "parentId": null,2418 "trashedAt": null,2419 "currentTitle": "Exemple · Thèse",2420 "currentVersion": 1,2421 "title": "Exemple · Thèse",2422 "existed": true,2423 "source": "current",2424 "exact": true,2425 "version": 1,2426 "versionId": null,2427 "versionAt": "2026-11-19T23:28:08.078Z",2428 "wordCount": 0,2429 "changedSince": false2430 },2431 {2432 "id": "d50d7a0b-4ae3-4740-be08-4e27790f0254",2433 "icon": null,2434 "section": "projects",2435 "parentId": "20709b78-b934-40aa-8fa9-8698e5039d5a",2436 "trashedAt": null,2437 "currentTitle": "Exemple · Données",2438 "currentVersion": 1,2439 "title": "Exemple · Données",2440 "existed": true,2441 "source": "current",2442 "exact": true,2443 "version": 1,2444 "versionId": null,2445 "versionAt": "2026-11-19T23:28:08.091Z",2446 "wordCount": 6,2447 "changedSince": false2448 },2449 {2450 "id": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2451 "icon": null,2452 "section": "projects",2453 "parentId": "20709b78-b934-40aa-8fa9-8698e5039d5a",2454 "trashedAt": null,2455 "currentTitle": "Exemple · Revue de littérature",2456 "currentVersion": 1,2457 "title": "Exemple · Revue de littérature",2458 "existed": true,2459 "source": "current",2460 "exact": true,2461 "version": 1,2462 "versionId": null,2463 "versionAt": "2026-11-19T23:28:08.098Z",2464 "wordCount": 25,2465 "changedSince": false2466 },2467 {2468 "id": "495f8abd-a19d-485b-acc1-377b4e43ddd3",2469 "icon": null,2470 "section": "projects",2471 "parentId": "20709b78-b934-40aa-8fa9-8698e5039d5a",2472 "trashedAt": null,2473 "currentTitle": "Exemple · Carte du projet",2474 "currentVersion": 1,2475 "title": "Exemple · Carte du projet",2476 "existed": true,2477 "source": "current",2478 "exact": true,2479 "version": 1,2480 "versionId": null,2481 "versionAt": "2026-11-19T23:28:08.170Z",2482 "wordCount": 3,2483 "changedSince": false2484 }2485 ],2486 "relations": [2487 {2488 "id": "af53442d-1347-4ff3-ad2f-d5b6550f9222",2489 "fromId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2490 "toId": "07cd9555-0e33-4006-af38-9005598bdde8",2491 "sourceKind": "page",2492 "targetKind": "reference",2493 "kind": "cites",2494 "relType": "cites",2495 "origin": "system",2496 "note": null,2497 "validFrom": null,2498 "validTo": null,2499 "sourceBlockId": "dSno8OQ_kP",2500 "targetBlockId": null,2501 "createdAt": "2026-11-19T23:28:08.099Z",2502 "fromTitle": "Exemple · Revue de littérature",2503 "toTitle": "Generalized autoregressive conditional heteroskedasticity"2504 },2505 {2506 "id": "ec20b9d6-21ba-4294-b3e3-ed9fd4e895af",2507 "fromId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2508 "toId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",2509 "sourceKind": "page",2510 "targetKind": "page",2511 "kind": "link",2512 "relType": "related",2513 "origin": "system",2514 "note": null,2515 "validFrom": null,2516 "validTo": null,2517 "sourceBlockId": "dSno8OQ_kP",2518 "targetBlockId": null,2519 "createdAt": "2026-11-19T23:28:08.099Z",2520 "fromTitle": "Exemple · Revue de littérature",2521 "toTitle": "Exemple · Données"2522 },2523 {2524 "id": "72693b47-4de2-4c4c-9f23-e9bf70169092",2525 "fromId": "d50d7a0b-4ae3-4740-be08-4e27790f0254",2526 "toId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2527 "sourceKind": "page",2528 "targetKind": "page",2529 "kind": "relation",2530 "relType": "extends",2531 "origin": "user",2532 "note": null,2533 "validFrom": "2026-01-01T00:00:00.000Z",2534 "validTo": null,2535 "sourceBlockId": null,2536 "targetBlockId": null,2537 "createdAt": "2026-11-19T23:28:08.136Z",2538 "fromTitle": "Exemple · Données",2539 "toTitle": "Exemple · Revue de littérature"2540 }2541 ],2542 "references": [2543 {2544 "id": "07cd9555-0e33-4006-af38-9005598bdde8",2545 "citeKey": "tim1986generalized",2546 "title": "Generalized autoregressive conditional heteroskedasticity",2547 "authors": [2548 "Bollerslev, Tim"2549 ],2550 "year": 1986,2551 "pageId": null,2552 "createdAt": "2026-11-19T23:28:08.087Z"2553 }2554 ],2555 "removedSince": [],2556 "journalSince": "2026-11-19T21:42:40.365Z"2557}2558```25592560---25612562## 4.5 Knowledge health25632564### `GET /api/health/knowledge`25652566`?inactiveDays=<1..3650, default 30>` — an integer outside the range is clamped and the applied value is echoed in `inactiveDays`2567(§0.6). `score` is `{pages, truncated, issues}`: `pages` = live pages read, most recently changed first, at most 50 000;2568`truncated: true` (new key, integration pass) says older pages were left out — the cut used to be an unordered 20 000. Authenticated (the public liveness probe `GET /api/health` is unchanged). Computed from real2569data at each call, no model. Every section is `{ count, ids, items }` (`ids` ≤ 200 page / task ids, `items` ≤ 200 with details).25702571| Section | Definition | Item |2572|---|---|---|2573| `orphans` | live, non-archived, non-row, non-inbox pages without any accepted edge | `{id, title, icon, section, updatedAt}` |2574| `brokenLinks` | in a live page: a link / mention / `blockRef` / `canvasLink` to a page that does not exist (`missing`) or is in the trash (`trashed`); a block anchor that no longer exists in its page (`kind:"block"`); an attachment id (3.0 node attr or `/api/files/<id>`) that does not exist or is deleted (`kind:"file"`) | `{pageId, title, kind, targetId, targetBlockId?, blockId, reason}` — `blockId` = the block that holds the link |2575| `missingReferences` | a `citation` whose reference does not exist (`missing`) or is deleted (`deleted`) | `{pageId, title, refId, blockId, reason}` |2576| `potentialDuplicates` | same normalised title, or same text (≥ 5 words) | `{reason:"title"\|"content", pageIds, title}` |2577| `untitled` | non-archived pages titled ``, `Untitled` or `Sans titre` | `{id, section, updatedAt, empty}` |2578| `inactiveProjects` | top-level pages of the section `projects` whose whole subtree has not changed for `inactiveDays` | `{id, title, icon, lastActivityAt, idleDays}` |2579| `openTasks` | tasks not done, not deleted; plus `overdue` and `withoutDate` counts | `{id, title, dueAt, pageId, priority, overdue}` (≤ 100) |25802581`score: {pages, issues}` — `issues` is the sum of the counts above with `overdue` in place of all open tasks.25822583```http2584GET /api/health/knowledge2585```25862587```http2588HTTP 2002589```25902591```json2592{2593 "computedAt": "2026-11-19T23:28:08.256Z",2594 "inactiveDays": 30,2595 "score": {2596 "pages": 7,2597 "truncated": false,2598 "issues": 42599 },2600 "orphans": {2601 "count": 4,2602 "ids": [2603 "db26dee6-75cf-43ef-bfb3-df26094e1661",2604 "495f8abd-a19d-485b-acc1-377b4e43ddd3",2605 "20709b78-b934-40aa-8fa9-8698e5039d5a",2606 "acbd524f-4899-4964-8ac7-102ad893d29c"2607 ],2608 "items": [2609 {2610 "id": "db26dee6-75cf-43ef-bfb3-df26094e1661",2611 "title": "Exemple · Lectures",2612 "icon": null,2613 "section": "databases",2614 "updatedAt": "2026-11-19T23:28:08.182Z"2615 },2616 {2617 "id": "495f8abd-a19d-485b-acc1-377b4e43ddd3",2618 "title": "Exemple · Carte du projet",2619 "icon": null,2620 "section": "projects",2621 "updatedAt": "2026-11-19T23:28:08.170Z"2622 },2623 {2624 "id": "20709b78-b934-40aa-8fa9-8698e5039d5a",2625 "title": "Exemple · Thèse",2626 "icon": null,2627 "section": "projects",2628 "updatedAt": "2026-11-19T23:28:08.078Z"2629 },2630 {2631 "id": "acbd524f-4899-4964-8ac7-102ad893d29c",2632 "title": "it-f0ea9fbc ia",2633 "icon": null,2634 "section": "notes",2635 "updatedAt": "2026-11-19T23:16:44.139Z"2636 }2637 ]2638 },2639 "brokenLinks": {2640 "count": 0,2641 "ids": [],2642 "items": []2643 },2644 "missingReferences": {2645 "count": 0,2646 "ids": [],2647 "items": []2648 },2649 "potentialDuplicates": {2650 "count": 0,2651 "ids": [],2652 "items": []2653 },2654 "untitled": {2655 "count": 0,2656 "ids": [],2657 "items": []2658 },2659 "inactiveProjects": {2660 "count": 0,2661 "ids": [],2662 "items": []2663 },2664 "openTasks": {2665 "count": 1,2666 "overdue": 0,2667 "withoutDate": 0,2668 "ids": [2669 "910c305f-64c6-4d08-b584-28fbeb6fcc29"2670 ],2671 "items": [2672 {2673 "id": "910c305f-64c6-4d08-b584-28fbeb6fcc29",2674 "title": "Relire la section 2",2675 "dueAt": "2026-11-25T12:00:00.000Z",2676 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2677 "priority": "high",2678 "overdue": false2679 }2680 ]2681 }2682}2683```26842685---26862687## 4.6 Brief26882689### `GET /api/brief`26902691`?tz=<IANA zone>` (default: the server's `TZ`, `America/Toronto`); `400 bad_request` for an unknown zone. **No model is called.**26922693`recentNotes` (8 most recently modified live pages, outside the inbox and database rows) · `activeProjects` (top-level pages of the2694section `projects` with a change in their subtree in the last 14 days: `pages`, `openTasks`) · `tasks.overdue` / `tasks.dueToday` /2695`tasks.dueSoon` (the 6 days after today), « today » being the calendar day in `tz` · `unfiledCaptures` `{count, items ≤ 10}` ·2696`linkSuggestions` `{count, items ≤ 5}` — suggested page ↔ page edges awaiting a decision, each **`ai: true`** · `toRevisit` (≤ 82697connected pages nobody opened or edited for 30 days, most central first) · `aiSummary` — `null`, or the last summary explicitly2698requested `{ai: true, text, model, at}`. `aiSummary` is **only ever present after a `POST /api/brief/summary`** made by the owner:2699`GET` never calls a model and never stores anything (a non-null `aiSummary` seen on the scratch instance during the Core live tests2700was a fixture left by a unit suite; the suites now put the stored summary back as they found it).27012702```http2703GET /api/brief?tz=America/Toronto2704```27052706```http2707HTTP 2002708```27092710```json2711{2712 "generatedAt": "2026-11-19T23:28:08.259Z",2713 "date": "2026-11-19",2714 "timeZone": "America/Toronto",2715 "recentNotes": [2716 {2717 "id": "db26dee6-75cf-43ef-bfb3-df26094e1661",2718 "title": "Exemple · Lectures",2719 "icon": null,2720 "section": "databases",2721 "type": "database",2722 "updatedAt": "2026-11-19T23:28:08.182Z",2723 "wordCount": 02724 },2725 {2726 "id": "495f8abd-a19d-485b-acc1-377b4e43ddd3",2727 "title": "Exemple · Carte du projet",2728 "icon": null,2729 "section": "projects",2730 "type": "canvas",2731 "updatedAt": "2026-11-19T23:28:08.170Z",2732 "wordCount": 32733 },2734 {2735 "id": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2736 "title": "Exemple · Revue de littérature",2737 "icon": null,2738 "section": "projects",2739 "type": "page",2740 "updatedAt": "2026-11-19T23:28:08.098Z",2741 "wordCount": 252742 },2743 {2744 "id": "d50d7a0b-4ae3-4740-be08-4e27790f0254",2745 "title": "Exemple · Données",2746 "icon": null,2747 "section": "projects",2748 "type": "page",2749 "updatedAt": "2026-11-19T23:28:08.091Z",2750 "wordCount": 62751 },2752 {2753 "id": "20709b78-b934-40aa-8fa9-8698e5039d5a",2754 "title": "Exemple · Thèse",2755 "icon": null,2756 "section": "projects",2757 "type": "page",2758 "updatedAt": "2026-11-19T23:28:08.078Z",2759 "wordCount": 02760 },2761 {2762 "id": "acbd524f-4899-4964-8ac7-102ad893d29c",2763 "title": "it-f0ea9fbc ia",2764 "icon": null,2765 "section": "notes",2766 "type": "page",2767 "updatedAt": "2026-11-19T23:16:44.139Z",2768 "wordCount": 232769 }2770 ],2771 "activeProjects": [2772 {2773 "id": "20709b78-b934-40aa-8fa9-8698e5039d5a",2774 "title": "Exemple · Thèse",2775 "icon": null,2776 "lastActivityAt": "2026-11-19T23:28:08.170Z",2777 "pages": 4,2778 "openTasks": 12779 }2780 ],2781 "tasks": {2782 "overdue": [],2783 "dueToday": [],2784 "dueSoon": [2785 {2786 "id": "910c305f-64c6-4d08-b584-28fbeb6fcc29",2787 "title": "Relire la section 2",2788 "status": "todo",2789 "priority": "high",2790 "dueAt": "2026-11-25T12:00:00.000Z",2791 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2792 "pageTitle": "Exemple · Revue de littérature",2793 "blockId": "FKmM69LEHF",2794 "project": null2795 }2796 ]2797 },2798 "unfiledCaptures": {2799 "count": 0,2800 "items": []2801 },2802 "linkSuggestions": {2803 "count": 0,2804 "items": []2805 },2806 "toRevisit": [],2807 "aiSummary": null2808}2809```28102811### `POST /api/brief/summary`28122813Optional body `{ "tz": "<IANA zone>" }` → `{ "ai": true, "text", "model", "at", "costUsd" }`. One short model call over the titles2814and counts of the brief (never the note contents), only on this explicit request; the result is stored and returned by `GET` as2815`aiSummary`. `502 ai_empty` when the model returns nothing. <!-- AI-WORKSTREAM --> Provider seam: `routedBriefModel` in2816`src/lib/knowledge/brief.ts` (existing router, task `quick`); tested with an injected model only — **not verified against a real2817provider**. No example is given here for that reason.28182819---28202821## 4.7 Living blocks — `POST /api/query`28222823Resolves a `queryView` (or the live data of a `chart` with `source`) at display time. Read-only and safe to repeat (it is a POST2824because the query is a body; it needs `Origin`).28252826Body: `source` `tasks | pages | database | references | backlinks` · `databaseId?` · `viewId?` · `pageId?` uuids · `limit?` 1…5002827(default 25) · `filter?` `{ tag?, section?, status?, parentId? (uuid), text?, dueBefore?, dueAfter? }`.28282829→ `{ source, columns: [{key, label, type}], rows: [{id, pageId, …}], total, limit, table: {columns: string[], rows: (string|number|null)[][]}, resolvedAt }`2830(+ `databaseId, viewId, name` for `database`). `rows[i][column.key]` is the typed value; `table` is the same data flattened (ready2831for a `chart` node's `columns` / `rows`, or a native table). `total` counts beyond `limit`. Column `type` ∈ `text | number | date |2832checkbox | select | page | tags | url | json`.28332834| `source` | Rows | Filters | Order |2835|---|---|---|---|2836| `tasks` | tasks; `id` = task id, `pageId`, `blockId` | `status`: `open` (default) `\| todo \| doing \| done \| all`; `parentId` = tasks of that page; `tag` / `section` = of the task's page; `text` in the title; `dueBefore` (exclusive) / `dueAfter` (inclusive), ISO date or datetime | open first, due date, newest |2837| `pages` | live pages (no rows, no inbox) | `status`: `active` (default) `\| archived \| pinned \| all \|` any other value = `properties.status`; `section`; `parentId` = children; `tag`; `text` in title or text | last modified |2838| `database` | rows of `databaseId` (database id or host page id), through the database engine: the view's filter and sorts (`viewId`, default view otherwise), formulas, rollups, relations; hidden columns removed; select / status options resolved to their names | `text` = the database search | the view's |2839| `references` | references | `text` (title, key, authors); `parentId` = attached to or cited by that page; `status` = `verified` value | year desc, key |2840| `backlinks` | pages linking to `pageId` (or `filter.parentId`); `via` = link kinds (`link`, `ai`, `canvas`) | `text`, `section` | last modified |28412842Errors: `400` validation · `400 bad_request` (missing `databaseId` / `pageId`, bad `status`, bad date) · `404` (database or view).28432844```http2845POST /api/query28462847{2848 "source": "tasks",2849 "filter": {2850 "parentId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2851 "status": "all"2852 },2853 "limit": 102854}2855```28562857```http2858HTTP 2002859```28602861```json2862{2863 "source": "tasks",2864 "columns": [2865 {2866 "key": "title",2867 "label": "Tâche",2868 "type": "text"2869 },2870 {2871 "key": "status",2872 "label": "État",2873 "type": "select"2874 },2875 {2876 "key": "priority",2877 "label": "Priorité",2878 "type": "select"2879 },2880 {2881 "key": "dueAt",2882 "label": "Échéance",2883 "type": "date"2884 },2885 {2886 "key": "pageTitle",2887 "label": "Page",2888 "type": "page"2889 },2890 {2891 "key": "project",2892 "label": "Projet",2893 "type": "text"2894 }2895 ],2896 "rows": [2897 {2898 "id": "910c305f-64c6-4d08-b584-28fbeb6fcc29",2899 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",2900 "blockId": "FKmM69LEHF",2901 "title": "Relire la section 2",2902 "status": "todo",2903 "priority": "high",2904 "dueAt": "2026-11-25T12:00:00.000Z",2905 "completedAt": null,2906 "pageTitle": "Exemple · Revue de littérature",2907 "project": null2908 }2909 ],2910 "total": 1,2911 "limit": 10,2912 "table": {2913 "columns": [2914 "Tâche",2915 "État",2916 "Priorité",2917 "Échéance",2918 "Page",2919 "Projet"2920 ],2921 "rows": [2922 [2923 "Relire la section 2",2924 "todo",2925 "high",2926 "2026-11-25T12:00:00.000Z",2927 "Exemple · Revue de littérature",2928 null2929 ]2930 ]2931 },2932 "resolvedAt": "2026-11-19T23:28:08.263Z"2933}2934```29352936```http2937POST /api/query29382939{2940 "source": "database",2941 "databaseId": "db26dee6-75cf-43ef-bfb3-df26094e1661",2942 "limit": 102943}2944```29452946```http2947HTTP 2002948```29492950```json2951{2952 "source": "database",2953 "columns": [2954 {2955 "key": "5baddb10-dcbb-46ba-86d5-878db2099eed",2956 "label": "Name",2957 "type": "page"2958 },2959 {2960 "key": "626cdc7c-1ae3-4281-b5ca-a9439fa8d737",2961 "label": "Année",2962 "type": "number"2963 }2964 ],2965 "rows": [2966 {2967 "id": "0660e2fc-499b-44b9-86d9-115fc7d257ab",2968 "pageId": "67a70821-dc3a-4d76-8ade-6602d6cc873c",2969 "title": "Engle (1982)",2970 "icon": null,2971 "5baddb10-dcbb-46ba-86d5-878db2099eed": "Engle (1982)",2972 "626cdc7c-1ae3-4281-b5ca-a9439fa8d737": 19822973 }2974 ],2975 "total": 1,2976 "limit": 10,2977 "table": {2978 "columns": [2979 "Name",2980 "Année"2981 ],2982 "rows": [2983 [2984 "Engle (1982)",2985 19822986 ]2987 ]2988 },2989 "resolvedAt": "2026-11-19T23:28:08.266Z",2990 "databaseId": "b7b47434-f9a0-4267-a6fc-433e0ea48b5a",2991 "viewId": "69eb4f2b-0fff-481c-b994-9a783cdd80fc",2992 "name": "Exemple · Lectures"2993}2994```29952996```http2997POST /api/query29982999{3000 "source": "backlinks",3001 "pageId": "d50d7a0b-4ae3-4740-be08-4e27790f0254"3002}3003```30043005```http3006HTTP 2003007```30083009```json3010{3011 "source": "backlinks",3012 "columns": [3013 {3014 "key": "title",3015 "label": "Page",3016 "type": "page"3017 },3018 {3019 "key": "section",3020 "label": "Espace",3021 "type": "select"3022 },3023 {3024 "key": "updatedAt",3025 "label": "Modifiée",3026 "type": "date"3027 }3028 ],3029 "rows": [3030 {3031 "id": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",3032 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",3033 "title": "Exemple · Revue de littérature",3034 "icon": null,3035 "section": "projects",3036 "updatedAt": "2026-11-19T23:28:08.098Z",3037 "via": [3038 "link"3039 ]3040 }3041 ],3042 "total": 1,3043 "limit": 25,3044 "table": {3045 "columns": [3046 "Page",3047 "Espace",3048 "Modifiée"3049 ],3050 "rows": [3051 [3052 "Exemple · Revue de littérature",3053 "projects",3054 "2026-11-19T23:28:08.098Z"3055 ]3056 ]3057 },3058 "resolvedAt": "2026-11-19T23:28:08.269Z"3059}3060```30613062---30633064## 4.8 Canvas30653066A canvas is a page with `type: "canvas"` (its `content` stays an empty document) plus one canvas row. Create it with3067`POST /api/pages { id?, title, type: "canvas", parentId?, section? }` — the canvas row is created in the same transaction (empty3068`spn-canvas-1`, `version: 1`). Trash / restore / purge are those of the page (purge → tombstones `page` + `canvas`).30693070`data` (`spn-canvas-1`):30713072```jsonc3073{ "format": "spn-canvas-1",3074 "nodes": [ { "id": "n1", "kind": "text|page|image|pdf|link|drawing|shape|reference|math|table", "x": 0, "y": 0, "w": 240, "h": 120, "z": 0,3075 "text": "…", "pageId": "uuid", "attachmentId": "uuid", "url": "https://…", "refId": "uuid", "latex": "…",3076 "color": "#rrggbb", "shape": "rect|ellipse|diamond", "ink": "attachment uuid" } ],3077 "edges": [ { "id": "e1", "from": "n1", "to": "n2", "label": "…", "kind": "arrow|line", "color": "#rrggbb" } ],3078 "viewport": { "x": 0, "y": 0, "zoom": 1 } }3079```30803081Server validation (`400 bad_canvas`, or `413 bad_canvas` for size): `format` exact; `nodes` ≤ 5 000, `edges` ≤ 10 000, serialized3082size ≤ 4 MiB; node `id` unique string 1…64, `kind` a string ≤ 32 (**unknown kinds and unknown fields are kept**), `x y w h` finite3083numbers (`w, h ≥ 0`), `z` number; `pageId, attachmentId, refId, ink` UUIDs; `text, latex` ≤ 100 000 chars; `url` ≤ 2 000 and not3084`javascript:`; edge `id` unique, `from` / `to` are node ids of the same canvas, `label` ≤ 500; `viewport` `{x, y, zoom > 0}`.30853086### `GET /api/canvases/<pageId>`30873088→ `{ pageId, title, data, version, rev, updatedAt }` (readable in the trash too). `404 not_found` · `404 not_canvas` (the page is3089not of type `canvas`).30903091```http3092GET /api/canvases/495f8abd-a19d-485b-acc1-377b4e43ddd33093```30943095```http3096HTTP 2003097```30983099```json3100{3101 "pageId": "495f8abd-a19d-485b-acc1-377b4e43ddd3",3102 "title": "Exemple · Carte du projet",3103 "data": {3104 "edges": [],3105 "nodes": [],3106 "format": "spn-canvas-1",3107 "viewport": {3108 "x": 0,3109 "y": 0,3110 "zoom": 13111 }3112 },3113 "version": 1,3114 "rev": 619769,3115 "updatedAt": "2026-11-19T23:28:08.160Z"3116}3117```31183119### `PUT /api/canvases/<pageId>`31203121Body `{ "data": <spn-canvas-1>, "baseVersion": <int> }` — **`baseVersion` is required**.3122→ `200 { version, rev, updatedAt, unchanged }`. The write happens only if the canvas is still at `baseVersion` (one statement);3123otherwise `409 conflict` with the server copy and nothing is written — merge by node / edge id (take the server copy, re-apply the3124local changes of the ids the user touched) and send again with `server.version`. Saving exactly what is stored is a no-op3125(`unchanged: true`, same `version`). A trashed canvas → `404`.31263127Side effects: `canvas.edited` (coalesced, 10 min); the canvas page's `updatedAt` moves (it shows in « recent » and in the page feed);3128cards of kind `page` make the canvas a **backlink** of those pages (`links` of kind `canvas`, visible in `backlinks` of3129`GET /api/pages/<id>` and in `POST /api/query` source `backlinks`).31303131**Search (canvas workstream)**: a save also writes the text of the canvas into the canvas page — `plainText` = per node, in array3132order, its `text`, `latex` and `url` (each when present, one per line; a `table` card's Markdown reduced to its cells), then the3133edge `label`s, capped at 200 000 characters; `wordCount` follows. The page is queued for indexing like a page save, and the index3134worker reads a canvas page from that text (it has no document). Nothing changes in the request or the response. The canvas3135format, its operations and the merge rules every client must match are in `docs/next/CANVAS.md`.31363137```http3138PUT /api/canvases/495f8abd-a19d-485b-acc1-377b4e43ddd331393140{3141 "data": {3142 "format": "spn-canvas-1",3143 "nodes": [3144 {3145 "id": "n1",3146 "kind": "page",3147 "x": 0,3148 "y": 0,3149 "w": 240,3150 "h": 120,3151 "z": 0,3152 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1"3153 },3154 {3155 "id": "n2",3156 "kind": "text",3157 "x": 320,3158 "y": 20,3159 "w": 200,3160 "h": 80,3161 "z": 1,3162 "text": "Hypothèse H1",3163 "color": "#3157d5"3164 }3165 ],3166 "edges": [3167 {3168 "id": "e1",3169 "from": "n1",3170 "to": "n2",3171 "label": "motive",3172 "kind": "arrow"3173 }3174 ],3175 "viewport": {3176 "x": 0,3177 "y": 0,3178 "zoom": 13179 }3180 },3181 "baseVersion": 13182}3183```31843185```http3186HTTP 2003187```31883189```json3190{3191 "version": 2,3192 "rev": 619770,3193 "updatedAt": "2026-11-19T23:28:08.169Z",3194 "unchanged": false3195}3196```31973198```http3199PUT /api/canvases/495f8abd-a19d-485b-acc1-377b4e43ddd332003201{3202 "data": {3203 "format": "spn-canvas-1",3204 "nodes": [],3205 "edges": [],3206 "viewport": {3207 "x": 0,3208 "y": 0,3209 "zoom": 13210 }3211 },3212 "baseVersion": 13213}3214```32153216```http3217HTTP 4093218```32193220```json3221{3222 "error": "This canvas was changed in another session",3223 "code": "conflict",3224 "server": {3225 "version": 2,3226 "data": {3227 "edges": [3228 {3229 "id": "e1",3230 "to": "n2",3231 "from": "n1",3232 "kind": "arrow",3233 "label": "motive"3234 }3235 ],3236 "nodes": [3237 {3238 "h": 120,3239 "w": 240,3240 "x": 0,3241 "y": 0,3242 "z": 0,3243 "id": "n1",3244 "kind": "page",3245 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1"3246 },3247 {3248 "h": 80,3249 "w": 200,3250 "x": 320,3251 "y": 20,3252 "z": 1,3253 "id": "n2",3254 "kind": "text",3255 "text": "Hypothèse H1",3256 "color": "#3157d5"3257 }3258 ],3259 "format": "spn-canvas-1",3260 "viewport": {3261 "x": 0,3262 "y": 0,3263 "zoom": 13264 }3265 },3266 "updatedAt": "2026-11-19T23:28:08.169Z"3267 }3268}3269```32703271```http3272PUT /api/canvases/495f8abd-a19d-485b-acc1-377b4e43ddd332733274{3275 "data": {3276 "format": "v0"3277 },3278 "baseVersion": 23279}3280```32813282```http3283HTTP 4003284```32853286```json3287{3288 "error": "Invalid canvas: data.format must be \"spn-canvas-1\"",3289 "code": "bad_canvas"3290}3291```32923293```http3294GET /api/canvases/a875edb2-ed14-4a41-a91c-8fdf8053f6c13295```32963297```http3298HTTP 4043299```33003301```json3302{3303 "error": "This page is not a canvas",3304 "code": "not_canvas"3305}3306```33073308---33093310## 4.9 Semantic zoom33113312### `GET /api/pages/<id>/zoom?level=1|2|3` (default 2)33133314- **3** → `{ level: 3, pageId, title, version, updatedAt, ai: false, content }` — the full document.3315- **2** → the outline, computed without any model: `{ level: 2, pageId, title, version, updatedAt, ai: false, sections }`. One3316 section per top-level heading (any level), preceded by a section with `heading: null`, `level: 0` for the text before the first3317 heading. `sections[]`: `blockId` (of the heading; of the first block for the leading section) · `level` 0…6 · `heading` ·3318 `firstSentence` — of the first non-empty block of the section: up to the first `.`, `!`, `?` or `…` followed by whitespace or the3319 end, at most 240 characters (cut on a word + `…`) · `words` · `blocks` (non-empty body blocks).3320- **1** → <!-- AI-WORKSTREAM --> AI synopsis, cached by content hash and always marked `ai: true` with `model` and `generatedAt`3321 (shape and the dedicated route `GET | POST /api/pages/<id>/zoom/ai` in `API-NEXT-AI.md`). **Without `cachedOnly=1` a missing3322 synopsis is generated: a paid model call.** With `?cachedOnly=1` no provider is ever called (`status: "missing"` when nothing3323 valid is cached) — what a client sends on first paint, and what every automated suite sends.33243325Works on a trashed page. `400 bad_request` for another level.33263327```http3328GET /api/pages/a875edb2-ed14-4a41-a91c-8fdf8053f6c1/zoom?level=23329```33303331```http3332HTTP 2003333```33343335```json3336{3337 "level": 2,3338 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",3339 "title": "Exemple · Revue de littérature",3340 "version": 1,3341 "updatedAt": "2026-11-19T23:28:08.098Z",3342 "ai": false,3343 "sections": [3344 {3345 "blockId": "406lGFlGau",3346 "level": 1,3347 "heading": "Volatilité conditionnelle",3348 "firstSentence": "Le modèle fondateur est Bollerslev 1986.",3349 "words": 23,3350 "blocks": 43351 }3352 ]3353}3354```33553356```http3357GET /api/pages/a875edb2-ed14-4a41-a91c-8fdf8053f6c1/zoom?level=1&cachedOnly=13358```33593360```http3361HTTP 2003362```33633364```json3365{3366 "pageId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1",3367 "level": 1,3368 "contentHash": "f170bd35bf5f766fe7fa0a3cf609276d",3369 "ai": false,3370 "status": "missing",3371 "synopsis": null,3372 "model": null,3373 "provider": null,3374 "generatedAt": null,3375 "cached": false,3376 "costUsd": null,3377 "title": "Exemple · Revue de littérature",3378 "version": 13379}3380```33813382<!-- AI-WORKSTREAM -->3383## 4.10 – 4.14 (AI workstream)33843385Documented in `docs/next/API-NEXT-AI.md`: §4.10 Ask (`POST /api/ai/chat` `scope`, `POST /api/ai/action` new actions), §4.11 Models3386(`GET /api/ai/models`), §4.12 Capture extensions and inbox suggestions (`GET /api/inbox/<id>/suggestions`, `POST /api/inbox/<id>/apply`),3387§4.13 Voice (`POST /api/audio/<attachmentId>/transcribe`, `GET /api/audio/<attachmentId>`), §4.14 Research3388(`GET /api/research/export.tex`, `GET /api/research/references?ids=`).3389<!-- /AI-WORKSTREAM -->33903391---33923393## 4.15 Files, purge, identifiers, parent cycles33943395### `GET /api/files/<id>` — Range33963397Always sent: `Accept-Ranges: bytes`, `ETag: "<sha256 of the content>"`, `Content-Length`, `Cache-Control: private, max-age=31536000, immutable`.3398One range per request: `Range: bytes=a-b`, `bytes=a-`, `bytes=-n` → `206` with `Content-Range: bytes a-b/<size>`. An unsatisfiable3399range → `416` with `Content-Range: bytes */<size>`. Several ranges or a malformed header → the whole file (`200`). `If-Range` with3400another ETag → the whole file. **A soft-deleted attachment answers `404`** (2.x kept serving it); `410 gone` when the file is missing3401on disk. Inline `Content-Disposition` now also for `audio/mp4`, `audio/x-m4a`, `audio/wav`, `audio/webm`, `audio/ogg`, `application/json`.34023403```http3404GET /api/files/725b9723-c31a-40a9-b2ca-6b2f7e48c72f3405Range: bytes=0-93406```34073408```http3409HTTP 2063410content-range: bytes 0-9/2003411accept-ranges: bytes3412content-length: 103413content-type: audio/mpeg3414etag: "295cbb667c2d2380418d4c7576c666c4f1690de2a2433f0e301bd5923377f8ed"3415```34163417`<10 bytes>`34183419```http3420GET /api/files/725b9723-c31a-40a9-b2ca-6b2f7e48c72f3421Range: bytes=500-3422```34233424```http3425HTTP 4163426content-range: bytes */2003427accept-ranges: bytes3428content-type: audio/mpeg3429etag: "295cbb667c2d2380418d4c7576c666c4f1690de2a2433f0e301bd5923377f8ed"3430```34313432`<0 bytes>`34333434### Purge (`DELETE /api/pages/<id>?purge=1`, `DELETE | POST /api/trash`) — step-up still required34353436Permanently deleting a page now also deletes:34373438- **the sub-pages that were moved to the trash by the same action as that page** (trashing a page trashes its live sub-pages in one3439 statement; they share its `deletedAt`). 2.x left them orphaned in the trash;3440- **the attachments of the deleted pages**: rows (→ `attachment` tombstones), their search index, and the file on disk — except an3441 attachment that something surviving still uses (another page whose document references it, a reference whose PDF it is); a file3442 shared by another attachment row (same content) stays on disk.34433444It never deletes a **live** sub-page (restored on its own, or moved under a trashed page) nor a sub-page that was **trashed3445separately**: those are kept and re-attached to the top level (`parentId: null`). One `page.purged` event per deleted page.3446The answer of the routes is unchanged (`{"ok":true}` / `{ok, purged}`); `purged` counts pages.34473448### Identifiers34493450Any malformed id in a path or a query string answers `400` (it answered `500`): see §0.2.34513452```http3453GET /api/pages/not-a-uuid3454```34553456```http3457HTTP 4003458```34593460```json3461{3462 "error": "Validation: Invalid UUID",3463 "code": "bad_request"3464}3465```34663467### Parent cycles34683469`PATCH /api/pages/<id> { parentId }`: the new parent must be a page of the workspace (`400 bad_parent`) and must not be the page3470itself (`400`) or one of its descendants (`409 cycle`). Nothing is written when refused.34713472```http3473PATCH /api/pages/20709b78-b934-40aa-8fa9-8698e5039d5a34743475{3476 "parentId": "a875edb2-ed14-4a41-a91c-8fdf8053f6c1"3477}3478```34793480```http3481HTTP 4093482```34833484```json3485{3486 "error": "A page cannot be moved under one of its own sub-pages",3487 "code": "cycle"3488}3489```34903491### Tags34923493`GET /api/tags` → `[{id, name, color, pages}]`: `pages` is now the number of live pages carrying the tag (it was always 0).34943495```http3496GET /api/tags3497```34983499```http3500HTTP 2003501```35023503```json3504[3505 {3506 "id": "4ba442f8-4d7f-4c97-a5f1-d195e0a058b8",3507 "name": "31999de6",3508 "color": "gray",3509 "pages": 03510 },3511 {3512 "id": "dedf187a-bae4-4e64-bc08-27b617f2c768",3513 "name": "garch",3514 "color": "gray",3515 "pages": 13516 },3517 {3518 "id": "93eca24f-765d-4ff3-9424-06667d02854b",3519 "name": "hors-ligne",3520 "color": "gray",3521 "pages": 03522 },3523 {3524 "id": "9c19fc6f-1f44-41c7-afa6-b25a7453f3ad",3525 "name": "it-3de28bc7",3526 "color": "gray",3527 "pages": 03528 },3529 {3530 "id": "17a8d9b4-7a87-4327-ad6c-e808f6586440",3531 "name": "journal",3532 "color": "gray",3533 "pages": 03534 },3535 {3536 "id": "20cbf6ed-2a1e-480d-a0ad-07c168109cee",3537 "name": "offline",3538 "color": "gray",3539 "pages": 03540 },3541 {3542 "id": "e31f9c2e-00f0-4218-8e19-bb8004d5b7a4",3543 "name": "thèse",3544 "color": "gray",3545 "pages": 23546 }3547]3548```35493550---35513552### Search — `GET /api/search` (2.x route; what a 3.0 client must know)35533554`?q=&mode=quick|hybrid&limit=&semantic=0|1&kinds=§ion=&since=&until=&archived=1&group=1`.35553556- **`mode` absent = `quick`** (unchanged from 2.x): a title search in PostgreSQL, no provider, rows3557 `{id, title, icon, type, section, updatedAt}`.3558- > **`mode=hybrid` sends the query text to the embedding provider (a paid call, and the text leaves the server) unless3559 > `semantic=0`.** `semantic` defaults to `1`. A client that wants a local, free, private search sends3560 > `mode=hybrid&semantic=0` (full-text + trigram only). The automated suites and the perf probe always send `semantic=0`.35613562### Database query filters — `POST /api/databases/<id>/query`, `POST /api/databases/<id>/rows/bulk`35633564`filter` / `extraFilter` (and `all.filter` / `all.extraFilter` of a bulk action) accept: a group `{"and":[…]}` or `{"or":[…]}`3565(rules and nested groups, depth ≤ 4), `{}` or `null` (no filter), **or one bare rule** `{"property":"<id>","op":"<op>","value":…}`,3566read as `{"and":[rule]}` (it was silently dropped before the integration pass: the answer was every row — and a bulk action touched3567every row). Anything else → `400 bad_filter` (an object that is neither, a group that is also a rule, an unknown property or3568operator, a non-object). A filter is never ignored.35693570### Research tasks and references (2.x routes)35713572- `POST | PATCH /api/research/tasks`: `dueAt` follows the bare-date rule of §0.6 (12:00 UTC; an unparsable date → `400 bad_request`,3573 it used to answer 500).3574- `GET /api/research/references?ids=<uuid,…>` (≤ 200) → exactly those references, each with `label` (author–year) and `citation`3575 (formatted entry); ids that do not exist **or are deleted** are listed, comma-separated, in the response header `x-missing-ids`3576 (empty when none). `?projectId=<page id>` → the references attached to a page of that project or cited in its text.3577 `400 bad_id` for a malformed id, `400 too_many_ids`.3578- `POST /api/research/references` with a client `id`: see §0.3 (`200` + `x-existing: 1` on a replay, `409 reference_deleted`).35793580### Offline-first captures — `POST /api/pages` with `inboxAt` | `inbox` and `captureKind`35813582A capture made offline by a native client is a page created under its client `id`; so that it reaches the **server inbox**,3583`POST /api/pages` accepts three optional fields (integration pass):35843585- `inboxAt` — ISO date: the moment of the capture (kept as given) — or `inbox: true` (= now). Unparsable → `400 bad_request`.3586- `captureKind` — open string, 1–32 characters (`note`, `tasks`, `link`, `photo`, `file`, `audio`, `screenshot`, `selection`,3587 `document`, or a kind of your own). Given alone it implies `inbox: true`; in the inbox without a kind it is stored as `note`.35883589The page is then an inbox item like one made by `POST /api/capture`: listed by `GET /api/inbox`, `inboxAt` / `captureKind` in the3590page and in its feed row, one `capture.created` event (`data: {kind, attachments: 0, via: "pages"}`) next to `page.created`. The call3591stays idempotent on `id` (`200` + `x-existing: 1`, the stored page untouched — a replay never moves a filed note back to the inbox).3592Without these fields nothing changes (`inboxAt: null`, `captureKind: null`).35933594### Universal links — `GET /.well-known/apple-app-site-association`35953596Public. `webcredentials` is unchanged; `applinks` is new: `/p/*` (a page, with an optional `#<blockId>` fragment) opens in the3597iOS / iPadOS app when it is installed.35983599```json3600{ "webcredentials": { "apps": ["3YM54G49SN.ai.spboucher.spnotes", "3YM54G49SN.ai.spboucher.spnotes.ios"] },3601 "applinks": { "details": [ { "appIDs": ["3YM54G49SN.ai.spboucher.spnotes.ios"], "components": [ { "/": "/p/*", "comment": "a page, optional #blockId" } ] } ] } }3602```36033604### Capture kinds36053606`POST /api/capture` accepts `kind`: `note | idea | tasks | link | photo | file | audio | screenshot | selection | document`3607(the last three since the productivity merge; details and examples in `API-NEXT-AI.md` §5.0). `400 bad_request` for another kind.36083609### Liveness — `GET /api/health`36103611Public, unchanged keys. `version` is now the same string as `GET /api/meta` (`3.0.0…`; it reported the raw `APP_VERSION` of the3612environment, e.g. `2.0.0-dev`), and `time` is ISO-8601 UTC.36133614---36153616## 5. Error codes36173618| HTTP | `code` | Where | Meaning |3619|---|---|---|---|3620| 400 | `bad_request` | everywhere | malformed id, date, number or enum; a body that fails its schema (`"error": "Validation: …"`); invalid JSON; a page set as its own parent |3621| 400 | `bad_filter` / `bad_sort` | database query, bulk | filter / sort not understood (unknown property or operator, wrong shape) |3622| 400 | `last_view` | `DELETE …/views` | the only view of a database cannot be deleted |3623| 400 | `bad_id` / `too_many_ids` | `/api/research/references` | malformed id in `ids`, `projectId`, `pageId`, `attachmentId`; more than 200 ids |3624| 400 | `bad_cursor` | `/api/sync`, `/api/events`, `/api/tasks?since=` | cursor not usable |3625| 400 | `bad_kinds` | `/api/sync`, `/api/events` | unknown kind; `kinds` lists the valid ones |3626| 400 | `bad_view` | `/api/graph` | unknown `view` |3627| 400 | `bad_page` | tasks, concepts | the page is not a (live) page of the workspace |3628| 400 | `bad_parent` | `PATCH /api/pages/<id>` | unknown parent |3629| 400 | `bad_node` | relations | a node does not exist / same node twice; `field` (`fromId` \| `toId`) |3630| 400 | `bad_document` | pages | document refused (structure or attr limits) |3631| 400 / 413 | `bad_canvas` | canvas | canvas refused (413: too large) |3632| 401 | `unauthenticated` | everywhere | no valid session |3633| 403 | `csrf` | mutations | missing or foreign `Origin` |3634| 403 | `reauth_required` | purge | passkey verified more than 5 minutes ago |3635| 404 | `not_found` | everywhere | well-formed id, no such object (every 404 carries it now, 2.x routes included) |3636| 404 | `not_canvas` | canvas | the page exists and is not a canvas |3637| 409 | `conflict` | pages, canvases, restore | `baseVersion` is stale; `server` = current copy |3638| 409 | `cycle` | `PATCH /api/pages/<id>` | the parent is a descendant of the page |3639| 409 | `id_taken` | creates | the id belongs to another workspace / parent |3640| 409 | `relation_exists` | relations | same (from, to, relType); `id`, `status` |3641| 409 | `concept_exists` | concepts (create and rename) | same name; `id`, `status` |3642| 409 | `reference_deleted` | `POST /api/research/references` | the client id belongs to a deleted reference; `id`, `deletedAt` |3643| 409 | `invalid_state` | agents, inbox | default code of a 409: the object is not in a state that allows the action |3644| 409 | `derived_edge` | relations | the edge comes from a document (or is a link suggestion): not editable this way |3645| 409 | `row_deleted` | database rows | the client id belongs to a deleted row |3646| 410 | `gone` | files | file missing on disk |3647| 416 | — | files | unsatisfiable range (no JSON body) |3648| 500 | `internal` | everywhere | server bug; `requestId` |3649| 501 | `not_implemented` | zoom level 1 | feature not provided by this server yet |3650| 502 | `ai_empty` | brief summary | the model returned nothing |36513652---36533654## 6. Deviations from SPEC v1 and known limits365536561. **`canvas.edited` is coalesced** like `page.edited` (SPEC lists coalescing for `page.edited` only): a canvas autosaves on every3657 gesture and would otherwise flood the journal.36582. **Extra columns** beyond SPEC §3: `knowledge_edges.updated_at`; `concepts.model / created_at / updated_at / decided_at`;3659 `page_concepts.block_id / model / created_at / decided_at`; `knowledge_insights.origin / fingerprint / decided_at`;3660 `canvases.workspace_id / created_at`; `database_properties|views|rows.workspace_id` (needed to scope the feed and the tombstones);3661 `knowledge_events.entity_id` is text (a tag has no uuid). The unique index of `knowledge_edges` now includes `rel_type`.36623. **`knowledge_edges.source_kind / target_kind`** are the 3.0 names; the 2.x columns `from_type / to_type` are still written with3663 the same values.36644. **Time machine**: states between two history entries cannot be rebuilt (the history is a snapshot every 10 minutes / 20 saves,3665 not a log of every save) — reported through `source` / `exact` rather than hidden. Edges deleted before 3.0 are unknown.36665. **Task ↔ document**: one direction is automatic (document → task); see §4.2.36676. **`reference`, `database_property`, `database_view`, `database_row` creates** answer `201` on an idempotent repeat (no3668 `x-existing` header): their 2.x routes return the object directly and were kept as they are.36697. **`GET /api/tasks` and `POST|PATCH /api/tasks`** return three more keys than 2.x (`blockId`, `deletedAt`, `rev`; `rev`, `blockId`3670 for the row form). Additive.36718. **Saving the same tag set again** no longer rewrites the page's tags (2.x deleted and re-inserted them, bumping `rev` twice).36729. **`DELETE /api/pages/<unknown id>`** still answers `200 {ok:true, trashed:1}` (2.x contract kept for shipped clients); nothing is3673 written and nothing is journaled.367410. The **web editor** does not yet keep `id` on `listItem` / `taskItem` (Tiptap drops unknown attrs until the web workstream3675 registers them): the server re-attaches the same ids at each save (§0.4), so they are stable anyway.367611. The `POST /api/pages/<id>/versions/<vid>/restore` route is new (SPEC called it "existing"); the 2.x3677 `POST /api/pages/<id>/versions {version}` is unchanged.36783679---36803681## 7. Testing against the scratch instance36823683**Integration instance (all web workstreams merged, the one the native live tests use):** worktree `~/dev/note-next-int` (branch3684`next-int`, database `note_next_int_dev`, `http://localhost:8486`), server **and worker** managed by3685`bash ~/dev/note-next-int-data/srv.sh start|stop|restart|build`; a session token:3686`set -a && . ./.env && set +a && node_modules/.bin/tsx scripts/dev-session.ts`. A full `pnpm test:e2e` run resets passkeys and3687**revokes every session** of the scratch database at its start (the auth journeys need a clean state): make a new token afterwards.3688The paragraphs below describe the foundation instance; the commands are the same with the paths and port above.36893690On `M4M64c`, worktree `~/dev/note-next` (branch `next`, database `note_next_dev`, `http://localhost:8483`, bound to 127.0.0.1):36913692```bash3693ssh M4M64c3694cd ~/dev/note-next3695bash scripts/next-dev-server.sh status # start | stop | status (pid: ~/dev/note-next-data/web.pid, log: web.log)3696TOKEN=$(bash scripts/next-dev-server.sh token) # a session token for the owner of the scratch database (dev only, no passkey)3697curl -s -H "Cookie: __Host-note_session=$TOKEN" http://localhost:8483/api/meta3698curl -s -H "Cookie: __Host-note_session=$TOKEN" -H "Origin: http://localhost:8483" -H "Content-Type: application/json" \3699 -d '{"title":"Essai"}' http://localhost:8483/api/tasks3700```37013702From the laptop: `ssh -N -L 8483:127.0.0.1:8483 M4M64c`, then use `http://localhost:8483` with the same cookie and3703`Origin: http://localhost:8483`. The token is a real session of the scratch database (90 days); a session made this way counts as3704freshly verified for 5 minutes (purge routes answer `403 reauth_required` afterwards — make a new token). No worker runs for this3705instance: indexing, the `graph-insights` AI job and transcription are not processed (`POST /api/graph/insights/run` with3706`mode: "deterministic"` works in the request). No AI key is configured on it.37073708Suites: `pnpm test` (unit / integration, scratch database) · `pnpm test:http` (HTTP-level, needs the server running) ·3709`bash scripts/next-migration-check.sh` (migration 0003 applied, rolled back and re-applied on a throw-away copy of the scratch3710database). Regenerate this file: `node_modules/.bin/tsx scripts/next-api-examples.ts && python3 scripts/next-api-doc.py`.3711