API — SP Note Next, AI workstream (v3.0, branch next-ai)
Contract for the native teams (SPNotesCore, macOS, iOS/iPadOS) and the web UI. It covers SPEC §3.5, §4.9 (level 1), §4.10–§4.14 and the
smart database properties. Everything else is in docs/next/API-NEXT.md (foundation workstream).
Every example below is a real response of the scratch instance (note_next_ai_dev, 2026-11-19), shortened only where marked ….
Prices are USD per 1M tokens as stored in the catalogue; costs are the catalogue price × the tokens the provider reported.
0.0 Integration pass (2026-11-19, branch next-int) — what changed in the routes of this document
The rules are written once in API-NEXT.md §0.2 (every error carries a code), §0.5 (DELETE is idempotent) and §0.6 (ISO dates,
JSON numbers, bare dates at 12:00 UTC, clamping). For the routes documented here:
| Route | Before | After |
|---|---|---|
any error without a specific code (/api/inbox/…, /api/audio/…, /api/research/…, /api/databases/…/ai…) |
{"error": …} |
{"error": …, "code": "<default of the status>"} — bad_request, not_found, invalid_state (409), too_large, upstream_error (502), internal (500) |
GET /api/ai/usage |
byModel[].calls / errors / inputTokens / outputTokens, byDay[].calls, byTask[].calls were strings ("337") |
JSON numbers (337); costUsd always a number |
GET /api/search/index-state |
pages, attachments, chunks, embedded, indexed_sources, stale strings; last_indexed, health.pending[].updatedAt, health.failed[].at raw PostgreSQL timestamps |
JSON numbers; ISO-8601 UTC strings (last_indexed may be null) |
GET /api/search?mode=quick (and no mode) |
updatedAt: "2026-11-19 13:45:47.060354-05" when q is not empty |
updatedAt: "2026-11-19T18:45:47.060Z" |
POST /api/research/references with a known id |
201, the stored row (also for a deleted reference) |
200 + x-existing: 1, the stored row; a deleted reference → 409 {"code":"reference_deleted","id","deletedAt"} (restore: POST /api/research/references/<id>?action=restore) |
GET /api/research/references?ids= |
— | unchanged; x-missing-ids also lists the ids of deleted references (documented) |
POST / PATCH /api/research/tasks dueAt: "2026-12-05" |
stored 2026-12-05T00:00:00.000Z; an unparsable date → 500 |
stored 2026-12-05T12:00:00.000Z (same rule as /api/tasks); unparsable → 400 bad_request |
DELETE /api/research/tasks/<id>, /api/research/references/<id>, /api/research/experiments/<id> |
200 {"ok":true} for an unknown id |
unchanged — this is now the documented rule for every DELETE |
GET /api/pages/<id>/zoom?level=1 |
— | unchanged; the automated suites call it with cachedOnly=1 only (no model call) |
No AI route gained or lost a field. GET /api/search?mode=hybrid embeds the query (paid, text sent to the provider) unless
semantic=0 — unchanged, now stated prominently in API-NEXT.md §4.15.
0. Conventions (unchanged from 2.x)
- Auth: session cookie. Mutations (
POST/PUT/PATCH/DELETE) needOrigin= the app origin (orSec-Fetch-Site: same-origin), else403 {"error":…,"code":"csrf"}. No session →401 {"code":"unauthenticated"}. - Errors:
{"error": "<human message>", "code": "<machine code>", …extra}+x-request-id. Ids that are not UUIDs →400(bad_idon the routes of this document). - Idempotency: optional
Idempotency-Keyon JSON mutations (stored answer replayed withidempotent-replay: true). SSE answers are never stored; the chat has its ownclientIdreplay. - SSE format:
content-type: text/event-stream. Each event is one linedata: <JSON>followed by a blank line; there are noevent:names — the discriminator is the JSON fieldtype. The stream always ends withdata: [DONE]. If the server fails mid-stream:{"type":"error","code":"server_error","retryable":true,"message":…}then[DONE]. - AI marking (SPEC §0.10): every AI result carries
ai:trueand/ormodel; clients must show it as AI-generated and never apply it without an explicit user action. Nothing in this document writes to a page, a tag, a link or a row on its own, except the two explicit "apply" calls (§5.2, §7.3) and the configured auto-run of a database property (§7.4). - Model ids: opaque strings ≤ 200 chars. Native-provider models keep their id (
claude-haiku-5-5,gpt-6-sol); models of OpenAI-compatible providers are namespaced<provider>:<remote id>(openrouter:anthropic/claude-fable-5). Send back exactly theidyou received.
1. Models and providers — GET /api/ai/models (SPEC §3.5, §4.11)
Query: all=1 (also disabled, unlisted and embedding models) · provider=<id> · creator=<id> · available=1 · q=<text> ·
unavailable=1 (include the models of OpenAI-compatible providers that have no key — several hundred for OpenRouter; they are
otherwise only counted in hiddenUnavailable).
{
"models": [ /* see below */ ],
"providers": [
{"id":"openai","name":"OpenAI","enabled":true,"lastDiscoveryAt":null,"status":"unknown","statusDetail":null,"kind":"openai","baseUrl":null,"keyEnv":"OPENAI_API_KEY","label":"OpenAI API","configured":true,"available":true,"logo":"/model-logos/generic.svg"},
{"id":"anthropic","name":"Anthropic","enabled":true,"lastDiscoveryAt":null,"status":"unknown","statusDetail":null,"kind":"anthropic","baseUrl":null,"keyEnv":"ANTHROPIC_API_KEY","label":"Anthropic API","configured":true,"available":true,"logo":"/model-logos/anthropic.svg"},
{"id":"openrouter","name":"OpenRouter","enabled":true,"lastDiscoveryAt":"2026-11-19T18:02:34.001Z","status":"no_key","statusDetail":"479 models listed from the public catalogue; OPENROUTER_API_KEY is not set","kind":"openai_compatible","baseUrl":"https://openrouter.ai/api/v1","keyEnv":"OPENROUTER_API_KEY","label":"OpenRouter","configured":false,"available":false,"logo":"/model-logos/openrouter.svg"},
{"id":"maclustr","name":"MacLustr LLM","enabled":true,"lastDiscoveryAt":"2026-11-19T18:02:34.001Z","status":"no_key","statusDetail":"MACLUSTR_LLM_API_KEY is not set","kind":"openai_compatible","baseUrl":"https://llm.spboucher.ai/v1","keyEnv":"MACLUSTR_LLM_API_KEY","label":"MacLustr","configured":false,"available":false,"logo":"/model-logos/generic.svg"}
],
"creators": [ {"id":"anthropic","name":"Anthropic","logo":"/model-logos/anthropic.svg","monogram":"AN","generic":false}, {"id":"openai","name":"OpenAI","logo":"/model-logos/generic.svg","monogram":"OA","generic":true}, … ],
"hiddenUnavailable": 479,
"routes": { … }, "defaultRoutes": { … }, "taskLabels": { … }, "benchmark": { … } // unchanged from 2.x
}keyEnv is the name of the environment variable; the key itself is never returned. configured = the variable is set;
available = configured and enabled. A provider without key is listed and never routed to.
A model (historical row fields kept, new fields after updatedAt):
{"id":"claude-haiku-5-5","provider":"anthropic","displayName":"Claude Haiku 5.5","category":"text","available":true,"enabled":true,
"contextWindow":1000000,"maxOutput":128000,"inputPrice":0.1,"cachedPrice":0.01,"outputPrice":0.5,
"pricingSource":"https://platform.claude.com/docs/en/about-claude/pricing","probes":{"text":{"ms":592,"status":"ok"},"…":{}},"benchmark":{"…":"summary.json aggregate, unchanged"},
"capabilities":{"…provider-declared keys, unchanged…":{},"text":true,"streaming":true,"tools":true,"structuredOutput":true,"jsonMode":true,"vision":true,"reasoning":true,"source":"measured"},
"notes":[],"discoveredAt":"2026-11-01T07:03:46.768Z","probedAt":"2026-11-01T07:03:46.768Z","benchmarkedAt":"2026-11-01T07:18:30.317Z","createdAt":"…","updatedAt":"…",
"creator":"anthropic","creatorName":"Anthropic","logo":"/model-logos/anthropic.svg","monogram":"AN",
"route":"anthropic","routeLabel":"Anthropic API","routeKind":"anthropic","routeLogo":"/model-logos/anthropic.svg","remoteId":"claude-haiku-5-5",
"context":1000000,"priceIn":0.1,"priceOut":0.5,"priceCached":0.01,"priceUnit":"USD per 1M tokens",
"listed":true,"unavailableReason":null,"benchmarked":true,"autoRoutable":true}The same creator through another route (returned with unavailable=1, provider=openrouter or all=1 while OpenRouter has no key):
{"id":"openrouter:anthropic/claude-fable-5","provider":"openrouter","displayName":"Anthropic: Claude Fable 5","category":"text","available":false,"enabled":true,
"contextWindow":1000000,"maxOutput":128000,"inputPrice":10,"cachedPrice":1,"outputPrice":50,"pricingSource":"https://openrouter.ai/api/v1/models","probes":{},"benchmark":{},
"capabilities":{"tools":true,"vision":true,"reasoning":true,"text":true,"streaming":true,"structuredOutput":true,"jsonMode":true,"source":"declared"},
"notes":["listed by the provider's /models; not probed or benchmarked — selectable manually, never routed automatically"],
"creator":"anthropic","creatorName":"Anthropic","logo":"/model-logos/anthropic.svg","monogram":"AN",
"route":"openrouter","routeLabel":"OpenRouter","routeKind":"openai_compatible","routeLogo":"/model-logos/openrouter.svg","remoteId":"anthropic/claude-fable-5",
"context":1000000,"priceIn":10,"priceOut":50,"priceCached":1,"priceUnit":"USD per 1M tokens",
"listed":true,"unavailableReason":"no_key","benchmarked":false,"autoRoutable":false}| field | meaning |
|---|---|
creator, creatorName, logo, monogram |
who made the model. logo = /model-logos/<creator>.svg, or /model-logos/generic.svg (then show monogram). Single-colour SVG: tint it (template image / CSS mask). Registry and licences: docs/next/MODEL-LOGOS.md, /model-logos/registry.json. |
route, routeLabel, routeKind, routeLogo, remoteId |
the API the call goes through (= provider id) — show it as a badge distinct from the creator. routeKind: openai | anthropic | openai_compatible. |
context |
context window in tokens (null = not published). Same value as the historical contextWindow. |
priceIn, priceOut, priceCached |
USD per 1M tokens (null = not published; 0 = free). Same values as inputPrice / outputPrice / cachedPrice. |
capabilities |
the stored provider object plus normalised booleans text, streaming, tools, structuredOutput, jsonMode, vision, reasoning (null = unknown) and source: measured (probed against the real API) | declared (provider catalogue) | unknown. |
available |
usable now. unavailableReason: no_key | provider_disabled | not_listed | disabled | null. listed = the provider still lists it. |
autoRoutable / benchmarked |
passed the measured probes → takes part in automatic routing. false = manual selection only (pass its id as model); automatic routing never picks it. |
Rules a picker must follow: group by creator; show the route badge; a model with available:false cannot be selected; "Auto" =
send model: null.
POST /api/ai/models (unchanged actions toggle, routes, budget; discover gains an optional provider):
{"action":"discover","provider":"openrouter"} → {"openrouter":{"listed":479,"status":"no key"}}. Discovery reads each provider's
GET {base_url}/models: context, prices and declared capabilities are stored as published. OpenRouter's catalogue is public and is read
even without a key (its models stay unavailable); another provider without key answers {"listed":0,"status":"no key"}.
Verified on 2026-11-19: GET https://llm.spboucher.ai/health → 200 {"status":"ok"}; GET https://llm.spboucher.ai/v1/models without
key → 401 (so the MacLustr catalogue appears once MACLUSTR_LLM_API_KEY exists).
2. Ask My Knowledge — POST /api/ai/chat (SSE, SPEC §4.10)
Body (2.x fields unchanged; new fields marked ★):
| field | type | notes |
|---|---|---|
message |
string 1–60 000 | required |
mode |
notes (default) | summarise | actions | contradictions | draft | general |
unchanged |
conversationId, clientId, pageId, model, task, useWorkspace, confirmExpensive, images, scopePageIds |
unchanged (model ≤ 200 chars now) |
|
★ scope |
all (default) | page | project | selection |
where the evidence may come from. Applies to modes notes, draft, contradictions; selection only to notes. |
★ projectId |
uuid | with scope:"project": that page and all its descendants. Without it the project is the root ancestor of pageId and all its descendants. |
★ selection |
string ≤ 20 000 | with scope:"selection": the only text the model may use (no search is run). |
★ selectionBlockId |
string | block the selection was made in; echoed as the citation's blockId only if that block exists in pageId. |
Events:
meta{conversationId, clientId, mode, model, provider, reason, task, sources: SourceRef[], weak: SourceRef[], evidence, sent, budgetNote, replayed, ★scope, ★scopePages, ★staleDropped}—scopePages= number of pages in the scope (null = unrestricted);staleDropped= retrieved passages discarded because their text is no longer in the page.text{delta}(repeated)done{messageId, content, usage, costUsd, latencyMs, ttftMs, sources: SourceRef[] (only the cited ones), evidence, invalidCitations: number[], uncited, replayed}needs_confirmation{reason, plan}— unchangederror{message, code, retryable, conversationId?, alternative?}— codes:not_configured,page_required,not_found,no_model,refused,provider_error,server_error, ★bad_scope, ★selection_required
SourceRef = {n, chunkId, pageId, title, icon, heading, blockId, excerpt, score, semantic, sourceType, ★blockIds, ★anchor, ★quote}:
blockId— the block that best supports the citation: inmeta, the block of the retrieved passage closest to the question; indone, the block closest to the sentence(s) of the answer carrying[n]. (2.x returned the first block of a ~350-token passage.)blockIds— every block of the passage;quote— the first 300 characters of the anchored block as it is in the page now.anchor—block(verified in the current page content) ·page(verified text, block without id) ·file(attachment text, no block) ·selection.- Open a citation with
/p/<pageId>#block-<blockId>(web) or by scrolling to the block with thatidattr (natives).
Guarantees:
- A citation marker
[n]that does not correspond to a retrieved source is removed fromcontentand reported ininvalidCitations. - A retrieved passage whose text is no longer in the page (page edited or block deleted since indexing) is dropped before the
model is called — a cited
blockIdalways exists in the page as it is now. - With no supporting source, no answering provider is called:
contentstarts with**No supporting note found.**,evidence:"none",costUsd:0. - An answer that cites none of its sources is withheld:
content=**No supporting note found.** The model wrote an answer without citing any of the retrieved passages, …,evidence:"insufficient",uncited:true,sources:[].
Request {"message":"Quelle est la pénalité de remboursement anticipé ?","scope":"page","pageId":"2eea0ded-…","model":"claude-haiku-5-5","clientId":"live-ask-page-02"}:
data: {"type":"meta","conversationId":"fe873d65-75c5-4827-89d2-37e1e48918f6","clientId":"live-ask-page-02","mode":"notes","model":"claude-haiku-5-5","provider":"anthropic","reason":"user selection","task":"chat","sources":[{"n":1,"chunkId":"a8a64c4b-bafb-4afe-b4a6-2594f911b667","pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","title":"Offre de la banque","icon":null,"heading":"Conditions","blockId":"XycxLnbyuq","excerpt":"Le taux fixe cinq ans proposé est de 4,29 %, garanti 90 jours.\nLa pénalité de remboursement anticipé équivaut à trois mois d intérêts.\nL amortissement restant est de vingt-deux ans.","score":0.016666666666666666,"semantic":0.644,"sourceType":"page","blockIds":["RttMYFvegP","XycxLnbyuq","8As7edcAjg"],"anchor":"block","quote":"La pénalité de remboursement anticipé équivaut à trois mois d intérêts."}],"weak":[],"evidence":"ok","sent":{"pageChars":0,"excerpts":1,"references":0,"images":0,"history":0,"embeddedBy":"openai","rankedBy":null},"budgetNote":null,"replayed":false,"scope":"page","scopePages":1,"staleDropped":0}
data: {"type":"text","delta":"La"}
data: {"type":"text","delta":" pénalité de rembours"}
…
data: {"type":"done","messageId":"e52caff5-2aa9-4bea-aafe-46431bc80021","content":"La pénalité de remboursement anticipé équivaut à trois mois d'intérêts [1].","usage":{"inputTokens":553,"outputTokens":34,"cachedTokens":0,"reasoningTokens":0},"costUsd":0.00007230000000000001,"latencyMs":1213,"ttftMs":953,"sources":[{"n":1,"chunkId":"a8a64c4b-…","pageId":"2eea0ded-…","title":"Offre de la banque","icon":null,"heading":"Conditions","blockId":"XycxLnbyuq","excerpt":"…","score":0.016666666666666666,"semantic":0.644,"sourceType":"page","blockIds":["RttMYFvegP","XycxLnbyuq","8As7edcAjg"],"anchor":"block","quote":"La pénalité de remboursement anticipé équivaut à trois mois d intérêts."}],"evidence":"ok","invalidCitations":[],"uncited":false,"replayed":false}
data: [DONE](The passage covers three paragraphs; the citation is anchored to the second one, XycxLnbyuq, which states the penalty.)
scope:"selection" — {"message":"Combien d années reste-t-il ?","scope":"selection","selection":"L amortissement restant est de vingt-deux ans.","pageId":"2eea0ded-…","model":"claude-haiku-5-5"}:
data: {"type":"meta",…,"sources":[{"n":1,"chunkId":"selection","pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","title":"Offre de la banque","icon":null,"heading":null,"blockId":null,"excerpt":"L amortissement restant est de vingt-deux ans.","score":1,"semantic":1,"sourceType":"selection","blockIds":[],"anchor":"selection","quote":"L amortissement restant est de vingt-deux ans."}],"weak":[],"evidence":"ok","sent":{"pageChars":0,"excerpts":1,"references":0,"images":0,"history":0,"embeddedBy":null,"rankedBy":null},…,"scope":"selection","scopePages":null,"staleDropped":0}
data: {"type":"done","messageId":"e2b5e9ee-…","content":"Il reste vingt-deux ans d'amortissement [1].","usage":{"inputTokens":476,"outputTokens":23,"cachedTokens":0,"reasoningTokens":0},"costUsd":0.0000591,"latencyMs":726,"ttftMs":485,"sources":[{…same source…}],"evidence":"ok","invalidCitations":[],"uncited":false,"replayed":false}(blockId is null here because the request carried no selectionBlockId.)
No support ({"message":"Quel est le prix du baril de pétrole ?","scope":"project","pageId":"2eea0ded-…"}):
data: {"type":"meta","conversationId":"27a49df1-…","clientId":"live-ask-none-02","mode":"notes","model":null,"provider":null,"reason":"no supporting source — no answering provider called","task":"chat","sources":[],"weak":[],"evidence":"none","sent":{"pageChars":0,"excerpts":0,"references":0,"images":0,"history":0,"embeddedBy":"openai","rankedBy":null},"budgetNote":null,"replayed":false,"scope":"project","scopePages":2,"staleDropped":0}
data: {"type":"text","delta":"**No supporting note found.** I searched your workspace and found nothing relevant enough to support an answer. I am not answering from general knowledge as if it came from your notes."}
data: {"type":"done","messageId":"228b8624-…","content":"**No supporting note found.** …","usage":null,"costUsd":0,"latencyMs":0,"ttftMs":null,"sources":[],"evidence":"none","invalidCitations":[],"uncited":false,"replayed":false}Scope error ({"message":"x","scope":"page"} without pageId) — nothing stored, nothing sent:
data: {"type":"error","code":"page_required","retryable":false,"message":"This scope works on an open page: open a page first."}
data: [DONE] 3. Inline actions — POST /api/ai/action (SSE, SPEC §4.10)
Body: {action, text ≤ 120 000, instruction? ≤ 4000, model? ≤ 200, language?, confirmExpensive?, ★pageId?}.
action = one of the 21 historical ids (rewrite, fix, translate, summarize, expand, explain, to_list, to_tasks, table, shorten, formal, simplify, translate_fr, translate_en, explain_math, continue, outline, study_notes, action_items, contradictions, custom) or ★
coherence, questions, synthesis, structure, links.
Pre-stream errors (JSON, unchanged): 400 bad_language, 400 no_instruction, 503 no_model / not_configured,
409 confirm_expensive {plan}; ★ 400 no_text (links with empty text).
coherence (logic, terminology, internal contradictions), questions (open questions the text raises), synthesis, structure
(a better outline + what to move/merge/cut) stream Markdown exactly like the historical actions; none is an expensive class:
data: {"type":"meta","model":"claude-haiku-5-5","provider":"anthropic","reason":"user selection","budgetNote":null}
data: {"type":"text","delta":"-"}
data: {"type":"text","delta":" Le taux de"}
…
data: {"type":"done","usage":{"inputTokens":262,"outputTokens":1230,"cachedTokens":0,"reasoningTokens":…},"costUsd":0.000641,"latencyMs":…}
data: [DONE]Failure inside the stream: {"type":"error","code":"refused"|"provider_error","retryable":true,"message":…}.
★ links — suggested internal links, as data; nothing is written. The server retrieves candidate pages (never the page pageId
itself nor a page it already links to), the model picks among them through a strict JSON schema, each pick is validated (an unknown
index is dropped; an anchorText that is not literally in text becomes null). No text events:
Request {"action":"links","text":"Avant de signer, vérifier la pénalité de remboursement anticipé et le taux fixe proposé.","pageId":"1280ae37-…","model":"claude-haiku-5-5"}:
data: {"type":"meta","model":"claude-haiku-5-5","provider":"anthropic","reason":"user selection","budgetNote":null}
data: {"type":"result","data":{"ai":true,"model":"claude-haiku-5-5","links":[{"pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","title":"Offre de la banque","icon":null,"blockId":"RttMYFvegP","excerpt":"Le taux fixe cinq ans proposé est de 4,29 %, garanti 90 jours. La pénalité de remboursement anticipé équivaut à trois mois d intérêts. L amortissement restant est de vingt-deux ans.","score":0.016666666666666666,"anchorText":"pénalité de remboursement anticipé","reason":"Donne les conditions chiffrées de la pénalité et du taux fixe évoqués dans la note."},{"pageId":"020cc747-b513-42f2-86b5-261f5ed48453","title":"Refinancement du triplex","icon":null,"blockId":"SLHKAchLmY","excerpt":"Dossier de refinancement du triplex de la rue Laurier, ouvert en novembre 2026.","score":0.015625,"anchorText":"taux fixe proposé","reason":"Dossier de refinancement qui contextualise l'offre de taux à vérifier avant signature."}],"candidates":4}}
data: {"type":"done","usage":{"inputTokens":886,"outputTokens":134,"cachedTokens":0,"reasoningTokens":0},"costUsd":0.00015560000000000001,"latencyMs":2269}
data: [DONE]When no candidate page exists no provider is called: meta {model:null, reason:"no candidate page — no provider called"},
result {data:{ai:true, links:[], candidates:0}}, done {usage:null, costUsd:0, latencyMs:0}. Invalid model JSON →
{"type":"error","code":"bad_output","retryable":true,…}. The client turns an accepted suggestion into a link on anchorText
(or inserts a mention) through a normal page save.
GET /api/ai/chat/plan is unchanged (it accepts the new action ids in action=).
4. Semantic zoom, level 1 — /api/pages/<id>/zoom/ai (SPEC §4.9)
The AI synopsis of a page, cached by content hash (title + Markdown). The foundation route GET /api/pages/<id>/zoom?level=1 returns
the same object (it calls the same function); this route also lets a client read the cache without spending, and regenerate.
GET /api/pages/<id>/zoom/ai→ synopsis; generated (one cheap model call, routequick) when missing or stale.?cachedOnly=1→ never calls a provider.?model=<id>→ manual model.POST /api/pages/<id>/zoom/ai{model?}→ regenerate.
{"pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","level":1,"contentHash":"20156a7accd058b5857a3744a185c6de","ai":true,"status":"ready","synopsis":"La note décrit une offre de prêt bancaire : un taux fixe sur cinq ans de 4,29 %, garanti pendant 90 jours, avec une durée d'amortissement restante de vingt-deux ans. Elle précise qu'un remboursement anticipé coûte une pénalité équivalant à trois mois d'intérêts. Aucune question ouverte ni comparaison n'y figure.","model":"claude-haiku-5-5","provider":"anthropic","generatedAt":"2026-11-19T18:22:22.977Z","cached":false,"costUsd":0.0001022}Second call: identical, with "cached":true (no provider call). With ?cachedOnly=1 before any generation:
{"pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","level":1,"contentHash":"20156a7accd058b5857a3744a185c6de","ai":false,"status":"missing","synopsis":null,"model":null,"provider":null,"generatedAt":null,"cached":false,"costUsd":null}status: ready | missing (cachedOnly, nothing valid cached) | empty (page without text — no call, ai:false).
Errors: 400 bad_id, 404 page, 503 no_model, 502 provider_error | refused (nothing is cached on failure).
Any edit or rename changes contentHash and invalidates the synopsis.
5. Smart Inbox (SPEC §4.12)
5.0 POST /api/capture — kinds (3.0, branch next-p-cv)
Body unchanged: {kind, text?, url?, attachmentIds?} → 201 {id, title, kind, inboxAt} (kind = the stored pages.capture_kind).
| kind | stored as | content |
|---|---|---|
note, tasks, link, photo, file |
same | unchanged from 2.x |
audio |
audio |
each audio attachment becomes an audio node (attachmentId, title, transcriptStatus:"none") instead of a file card, so the capture is a voice note that can be transcribed (§6); non-audio attachments keep their card |
screenshot |
screenshot |
like photo (image nodes); default title Screenshot · <date> |
document |
document |
a PDF attachment becomes a pdf node (attachmentId, name, page:1, annotations:[]), other files a file card |
selection |
selection |
text (required) as a blockquote; url = its source, either /p/<pageId> / /p/<pageId>#block-<blockId> (kept relative: the capture then appears in that page's backlinks) or an http(s) address; any other value is ignored |
idea |
note |
request-only alias: a note created with the icon 💡 (the stored kinds stay the ones of SPEC §4.12) |
5.1 GET /api/inbox/<id>/suggestions
AI suggestions for one capture: title, tags, destination, related pages, summary. Suggestions only — this route changes nothing.
Strict JSON schema; the model answers with indices into a candidate list built by the server, so a destination or a relation is always
an existing page; tags are normalised and flagged existing / new. Cached by content hash (title + text + tags of the capture) and
re-validated on every read. ?refresh=1 regenerates · ?cachedOnly=1 never calls a provider · ?model=<id>.
{"pageId":"d420eb53-5bce-4ee5-a419-5c70cef55c7a","contentHash":"c0218f0950c5aad9b1170269bc6f4f2c","status":"ready","ai":true,"model":"claude-haiku-5-5","provider":"anthropic","generatedAt":"2026-11-19T18:24:12.565Z","cached":false,"costUsd":0.00010823,
"suggestions":{
"title":{"value":"Rappeler la banque triplex","current":"rappeler la banque triplex"},
"tags":[{"name":"refinancement","existing":true},{"name":"triplex","existing":true},{"name":"banque","existing":true}],
"destination":{"section":"projects","parentId":"020cc747-b513-42f2-86b5-261f5ed48453","parentTitle":"Refinancement du triplex"},
"relations":[{"pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","title":"Offre de la banque","icon":null,"reason":"L'offre de la banque concerne probablement le même financement et la garantie de taux en question."}],
"summary":"Rappeler la banque pour demander si la garantie de taux de 90 jours peut être prolongée dans le cadre du refinancement du triplex."}}Each key of suggestions may be null / empty: title is null when the model keeps the current title; destination is
{section, parentId:null, parentTitle:null} when only a section is proposed, or null. status:"empty" (ai:false, empty
suggestions) for a capture with no title and no text. Errors: 400 bad_id, 404 page, 409 not_in_inbox,
404 not_generated (cachedOnly), 503 no_model, 502 provider_error | refused | bad_output.
5.2 POST /api/inbox/<id>/apply
Applies the subset the user chose, with the values sent (the user may have edited them). Only the keys present are applied.
Body (all optional, at least one): {title?: string ≤300, tags?: string[] ≤10, destination?: {section?: notes|documents|projects|research, parentId?: uuid|null}, relations?: [{pageId, reason?}] ≤10, summary?: string ≤1000}.
title→ the page is renamed (a version "before AI suggestion" is kept).tags→ added to the existing tags.relations→ accepted relations to those pages (knowledge_edges, kindai_suggested, statusaccepted).summary→ inserted as the first block, as anaiBlock(attrs.action = "summary") — it stays visibly AI.destination→ the capture is filed (leaves the inbox). Withoutdestinationit stays in the inbox.
{"actionId":"68415a83-438b-46cf-b85e-25bfba7246be","summary":"4 suggestions applied","applied":["title","summary","tags","relations"],"filed":false,"created":{"summaryBlockId":"AW23RJ67ft","tagsAdded":["refinancement","triplex","banque"],"edgeIds":["bed79a14-d9c0-45ba-b641-383f4ae40f9d"]}}Errors (validated before any write): 400 nothing_to_apply ({"error":"Nothing chosen to apply","code":"nothing_to_apply"}),
400 bad_section | bad_destination | bad_relation, 409 not_in_inbox, 409 conflict (page changed meanwhile).
5.3 Undo — POST /api/inbox/undo {actionId} (existing route)
Reverses the action journaled above exactly like a triage action: title, added tags, the inserted summary block, the created
relations and the filing. Later edits by the user (other tags, other text) are left alone. → {"ok":true,"already":false}
(already:true when repeated). The journal action name is suggestions.
6. Voice (SPEC §4.13)
6.1 POST /api/audio/<attachmentId>/transcribe
Body {summarize?: boolean, force?: boolean}. Queues the pg-boss job transcribe (never retried automatically: it is a paid call).
202— a job was queued:
{"queued":true,"jobId":"1b60aa7a-da87-4306-b323-e37c5f233ca9","attachmentId":"82f70f18-d19f-4d58-ba81-8a4d72099e17","status":"pending","transcript":[],"text":"","engine":null,"model":null,"language":null,"duration":null,"segments":null,"summary":null,"error":null,"costUsd":null,"requestedAt":"2026-11-19T18:22:31.175Z","finishedAt":null}200{"queued":false, …current state…}— a transcript already exists or is pending (no second call, no second charge).force:truetranscribes again;summarize:trueon a finished transcript without summary queues the summary only.- Errors:
400 bad_id·404unknown attachment ({"error":"Attachment not found"}) ·415 not_audio·413 too_large(> 25 MB, the engine's limit) ·503 not_configured(no OpenAI key) |queue_unavailable.
Accepted: audio/*, video/webm, video/mp4 in a container the engine reads (webm, m4a/mp4, mp3, wav, ogg, flac).
6.2 GET /api/audio/<attachmentId>
Poll every 2–3 s while status is pending.
{"attachmentId":"82f70f18-d19f-4d58-ba81-8a4d72099e17","status":"done",
"transcript":[{"t":0,"text":"Réunion du 19 novembre. Nous retenons le taux fixe de 5 ans."},{"t":4.4,"text":"Marie envoie les documents à la banque lundi matin."}],
"text":"Réunion du 19 novembre. Nous retenons le taux fixe de 5 ans. Marie envoie les documents à la banque lundi matin.",
"engine":"openai","model":"whisper-1","language":"french","duration":6.869999885559082,"segments":true,
"summary":{"at":"2026-11-19T18:22:36.405Z","text":"Réunion du 19 novembre. Ils retiennent un taux fixe de 5 ans. Marie enverra les documents à la banque lundi matin.","model":"gpt-5.4-mini","tasks":["Marie envoie les documents à la banque lundi matin."],"decisions":["Ils retiennent le taux fixe de 5 ans."]},
"error":null,"costUsd":null,"requestedAt":"2026-11-19T18:22:31.175Z","finishedAt":"2026-11-19T18:22:36.408Z"}(Real run: 6.8 s of French speech synthesized with macOS say, 32 KB m4a, transcribed in about 2 s. Transcripts stored after this
run round duration to 0.01 s.)
| field | meaning |
|---|---|
status |
none (never requested) | pending | done | failed |
transcript |
[{t: seconds from the start, text}] — exactly the audio node's transcript attr |
engine, model |
what actually produced the transcript (audio.transcriptEngine = "<engine>:<model>" is a reasonable client value) |
segments |
true when the model returns timestamps; false = text-only model, one segment at t:0 |
summary |
{text, decisions[], tasks[], model, at} or null — the audio node's summary attr |
error |
reason when failed; when done, a non-null value means the summary could not be produced (Summary not produced: …) |
costUsd |
null unless the owner set settings['ai.transcription_usd_per_minute'] (transcription prices are not in the catalogue) |
Engine choice: the transcription models the OpenAI account exposes are discovered live. On 2026-11-19 the account exposes
gpt-4o-mini-transcribe, gpt-4o-mini-transcribe-2025-03-20, gpt-4o-mini-transcribe-2025-12-15, gpt-4o-transcribe,
gpt-4o-transcribe-diarize, gpt-transcribe, whisper-1; whisper-1 is chosen because it returns segment timestamps
(verbose_json), then a diarising model, then text-only models. Override with settings['ai.transcription_model'].
Who writes the audio node: the client. When status becomes done, the editor copies transcript, transcriptStatus:"done",
transcriptEngine, summary into the node and saves the page normally (versioned). The server does not edit the page.
7. Smart database properties
The property type ai keeps working as in 2.x (config.prompt, manual "Generate" per cell). New: per-property configuration, a run
log, protection of hand-edited values, optional auto-run.
7.1 Configuration — /api/databases/<id>/ai/config
GET → {"tasks":["custom","summarize","classify","extract","detect-date","categorize"],"properties":[…]}:
{"tasks":["custom","summarize","classify","extract","detect-date","categorize"],"properties":[{"propertyId":"3981f845-97b9-47f0-b153-96ef517c8e4c","name":"Priorité IA","ai":{"task":"classify","prompt":"","choices":["Urgent","Normal","Plus tard"],"model":"claude-haiku-5-5","autoRun":true,"managed":false},"problem":null,"runs":{"queued":0,"done":1,"failed":0,"skipped":1,"costUsd":0.0000626,"lastAt":"2026-11-19T18:22:41.699Z"}}]}PUT {propertyId, ai: {task?, prompt? ≤4000, choices? string[] ≤40, model? | null, autoRun?, managed?}} (partial, merged) →
{"propertyId":"3981f845-97b9-47f0-b153-96ef517c8e4c","name":"Priorité IA","ai":{"task":"classify","prompt":"","choices":["Urgent","Normal","Plus tard"],"model":"claude-haiku-5-5","autoRun":true,"managed":false},"problem":null}ai field |
meaning |
|---|---|
task |
custom (free prompt, the 2.x behaviour) · summarize · classify (exactly one of choices) · extract (what prompt describes, copied faithfully) · detect-date (ISO YYYY-MM-DD) · categorize (zero or more of choices, or ≤ 3 free categories) |
prompt |
required for custom and extract; optional guidance otherwise. {{Property name}} placeholders. Mirrored in the historical config.prompt. |
choices |
allowed values for classify (≥ 2) / categorize |
model |
model override (an id of §1); null = measured route (quick / extract) |
autoRun |
recompute the cell when another value of the row changes (API row create / update) |
managed |
the property is AI-managed: the AI may overwrite a value typed by hand |
problem is a string when the configuration cannot run ("No prompt configured", "Classification needs at least two choices", …).
Errors: 400 not_ai_property, 404. The stored shape is database_properties.config.ai — the generic property PATCH still works.
An answer outside the task's contract (a class that is not a choice, an impossible date, invalid JSON) stores null, never a guess.
Cell values stay plain text ("Urgent", "2027-03-03", "a, b"), {"pending":true,"at":…} while queued, {"error":…} on failure.
7.2 Run — POST /api/databases/<id>/ai (existing route)
Body {propertyId, rowId | rowIds[] ≤200, force?}. Historical answer keys kept (ok, queued), plus runs and skipped.
A cell whose value was typed by hand is not overwritten unless the property is managed or force:true is sent:
{"ok":true,"queued":0,"runs":[{"rowId":"93e5f9e5-5f6e-4c40-ab8c-9ac28e28c524","runId":"d93a25ed-1f05-4353-ab79-f8f1e60082be","queued":false,"skipped":"user_edited"}],"skipped":[{"rowId":"93e5f9e5-5f6e-4c40-ab8c-9ac28e28c524","reason":"user_edited","runId":"d93a25ed-1f05-4353-ab79-f8f1e60082be"}]}skipped reasons: user_edited · bad_config · already_queued (pending < 5 min) · over_budget (auto-run only) ·
queue_unavailable. A skipped cell is left exactly as it was. "Typed by hand" = a non-empty value that differs from the output of
the last successful run of that cell.
7.3 Run log — GET /api/databases/<id>/ai/runs?propertyId=&rowId=&status=&limit=
Newest first, ≤ 500:
[{"id":"303848ec-ce88-471b-9923-92e0c4ba7f60","databaseId":"03f4d928-e8ad-4dea-b6cc-f307e04303d4","propertyId":"3981f845-97b9-47f0-b153-96ef517c8e4c","rowId":"93e5f9e5-5f6e-4c40-ab8c-9ac28e28c524","status":"done","trigger":"auto","task":"classify","model":"claude-haiku-5-5","provider":"anthropic","inputTokens":561,"outputTokens":13,"costUsd":0.0000626,"error":null,"createdAt":"2026-11-19T18:22:37.475Z","startedAt":"2026-11-19T18:22:38.173Z","finishedAt":"2026-11-19T18:22:41.153Z"}]status: queued | running | done | failed | skipped · trigger: manual | auto. (This run was triggered by creating
the row: the cell became "Urgent" 3.7 s later.)
7.4 Auto-run
After POST / PATCH /api/databases/<id>/rows, every AI property with autoRun:true is queued for the changed row — never when the
change only touched AI cells, never over a hand-edited value (unless managed), never when the daily AI budget is reached. The row
write never fails because of it. Clients poll the row (the existing 2.5 s polling while a value is pending) or the run log.
8. Research (SPEC §4.14)
8.1 GET /api/research/export.tex?projectId=<page id>[&format=tex|json|zip][&inline=1]
LaTeX article skeleton of a project = the page projectId and all its live descendants in tree order (database rows and archived
pages left out). No AI is involved. Root page body first (its "Abstract" / "Résumé" heading becomes \begin{abstract}), then one
\section per child page, nested by depth; hypothesis callouts are also collected in a "Hypotheses" section; the project's
experiments become "Methods notes"; equations are kept verbatim (inlineMath → $…$, blockMath → equation); images become
\includegraphics{figures/<attachment name>} placeholders; \cite{…} typed in the text is preserved; citation nodes become
\cite[locator]{key} (a missing reference becomes a visible [?] + a comment, never an invented key).
format=tex(default) →application/x-tex; headersx-export-report: {"pages":2,"sections":1,"citeKeys":0,"missingKeys":0,"missingRefs":0,"figures":0,"hypotheses":0,"experiments":0,"unknownNodes":[]}andx-bib-url: /api/research/references/export.bib?projectId=020cc747-…;inline=1omitscontent-disposition.
% Generated by SP Note — LaTeX skeleton of the project "Refinancement du triplex"
% 2 page(s), 0 cite key(s), 0 figure placeholder(s). Figures are expected in ./figures/ (see the ZIP export).
\documentclass[11pt]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{amsmath,amssymb}
\usepackage{graphicx}
\usepackage[normalem]{ulem}
\usepackage{hyperref}
\title{Refinancement du triplex}
\author{Simon-Pierre Boucher}
\date{\today}
\begin{document}
\maketitle
Dossier de refinancement du triplex de la rue Laurier, ouvert en novembre 2026.
\section{Offre de la banque}
% page 2eea0ded-b5b8-4abe-b560-75345504be80
\subsection{Conditions}
Le taux fixe cinq ans proposé est de 4,29 \%, garanti 90 jours.
…
\bibliographystyle{plain}
\bibliography{references}
\end{document}format=json→{"projectId", "title", "tex", "bib", "citeKeys":[], "missingKeys":[], "missingRefs":[], "figures":[{"attachmentId","name","file"}], "sections":1, "hypotheses":0, "experiments":0, "unknownNodes":[], "bibUrl"}—missingKeys= cited but absent from the library;figures[].file= the name used in\includegraphics{figures/<file>}.format=zip→application/zipwithmain.tex,references.bib,figures/<file>(the real attachments present on disk, ≤ 150 MB) andexport-report.json(figuresIncluded,figuresMissing,missingKeyList).
Errors: 400 bad_id ({"error":"projectId is required (a page id)","code":"bad_id"}), 400 bad_format, 404 not_found.
8.2 .bib companion — GET /api/research/references/export.bib?projectId=<page id>[&inline=1]
The existing BibTeX export, scoped to the project: references attached to any page of the project plus every library reference
cited by key or by a citation node in its text. (?pageId= and the whole-library form are unchanged.)
@article{doe2021prepayment,
author = {Doe, Jane and Roe, John},
title = {Mortgage Prepayment and the Term Structure},
journal = {Journal of Housing Finance},
year = {2021}
} 8.3 GET /api/research/references
?pageId=and no parameter — unchanged.- ★
?projectId=<page id>→ the same set as §8.2, as reference rows. - ★
?ids=<uuid,uuid,…>(≤ 200) → exactly those references, for resolvingcitationnodes; each row gainslabel(author–year) andcitation(formatted entry). Ids that do not exist — or belong to a deleted reference — are listed in the response headerx-missing-ids.
[{"id":"54879947-9c63-455b-8e67-afa8cab80953","workspaceId":"…","pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","citeKey":"doe2021prepayment","entryType":"article","title":"Mortgage Prepayment and the Term Structure","authors":["Jane Doe","John Roe"],"year":2021,"journal":"Journal of Housing Finance","doi":null,"url":null,"bibtex":"@article{doe2021prepayment,\n author = {Doe, Jane and Roe, John},\n …}","fields":{"year":"2021","title":"…","author":"Doe, Jane and Roe, John","journal":"Journal of Housing Finance"},"verified":"user","attachmentId":null,"createdAt":"2026-11-19T18:22:41.721Z","updatedAt":"2026-11-19T18:22:41.721Z","deletedAt":null,"label":"Doe & Roe (2021)","citation":"Doe, J., & Roe, J. (2021). Mortgage Prepayment and the Term Structure. Journal of Housing Finance."}]with x-missing-ids: 00000000-0000-4000-8000-000000000000. Errors: 400 bad_id, 400 too_many_ids.
- ★ (slice next-p-ra)
?attachmentId=<attachment id>→ the references whose attached PDF is that file, each withlabel; used by thepdfblock to save its annotations as extracts of that reference (extract id derived from attachment id + annotation id, seesrc/lib/research/pdf-extracts.ts;POST …/extracts {id,…}is idempotent on it).400 bad_idon a malformed id.
8.4 POST /api/research/papers — kind (slice next-p-ra, additive)
{title?, status?, venue?, kind?: "paper" | "project"}. Default paper = unchanged. project creates the root research page
(properties.researchKind = "project") and five child pages (Hypotheses, Methods notes, Equations, Results, Figures;
properties.researchRole), and answers the root page plus children: [{id, title, key}] — the tree export.tex turns into sections.
9. Error codes introduced by this workstream
| code | status | where |
|---|---|---|
bad_scope, selection_required |
SSE error |
chat |
no_text, bad_output |
400 / SSE error |
action links |
no_model |
503 | zoom, inbox suggestions (no eligible model / no key) |
provider_error, refused, bad_output |
502 | zoom, inbox suggestions |
not_generated |
404 | inbox suggestions with cachedOnly=1 |
not_in_inbox |
409 | inbox suggestions / apply |
nothing_to_apply, bad_section, bad_destination, bad_relation |
400 | inbox apply |
not_audio (415), too_large (413), not_configured, queue_unavailable (503) |
transcription | |
not_ai_property |
400 | database AI config / run |
bad_format, too_many_ids, bad_id |
400 | research, every route (malformed id) |
10. Data added (migration 0004_next_ai, additive; rollback 0004_next_ai.down.sql)
ai_providers + kind, base_url, key_env, label (rows openrouter, maclustr seeded) · ai_models + creator, route ·
tables ai_synopses, inbox_suggestions, audio_transcripts, ai_property_runs. New queue: transcribe. New settings keys:
ai.transcription_model, ai.transcription_models (cache of the discovered ids), ai.transcription_usd_per_minute.
ai_usage.task values added: zoom, inbox_suggest, transcribe, transcribe_summary, action:links (and action:<new id>).
Deviations from SPEC v1, to keep in mind when coding against it:
- §3.5 lists
context_window,price_in,price_out,capabilitiesas newai_modelscolumns: they already existed (context_window,input_price,output_price,capabilities) and are not duplicated — the API exposes them ascontext,priceIn,priceOut(and keeps the historical names). - §4.13 says the result is written into the
audionode "through a normal versioned save": that save is done by the client (§6.2); the server only stores the transcript inaudio_transcripts. - §4.9: level 1 lives at
/api/pages/<id>/zoom/aiin this branch;…/zoom?level=1is wired to it at merge. - Events (
ai.applied, …, SPEC §3.2) are not written by these routes yet:knowledge_eventsbelongs to migration 0003 (wired at merge).