Adding Internal API Route

Adding an internal API route in Trilium

The first decision is which routes/api/ directory. There are TWO, and the common assumption that all routes live server-side in apps/server/src/routes/api/ is wrong — that's the minority case. ~140 of the routes live in the core one:

A route you add only in routes.ts is invisible to the standalone build and cannot be driven by CoreApiTester. A core handler that imports node:* or touches process.env breaks the WASM build. Pick the wrong side and you either lose standalone support or break it.

Footgun checklist (read before you start)

1. Default to core. Note/branch/attribute/tree/search/revision/import logic is browser-safe → put it in packages/trilium-core/src/routes/api/ and register in index.ts's buildSharedApiRoutes. Only Node-only or genuinely server-scoped routes go in routes.ts. (Step 1.)
2. Async handler ⇒ asyncApiRoute, never apiRoute. apiRoute runs sql.transactional(cb) synchronously (route_api.ts:100) — hand it an async function and it commits an empty transaction immediately; your awaited writes land outside any transaction. (Step 2.)
3. Return conventions are implicit. object/array/string → 200; undefined/nothing → 204; [integerStatus, body] tuple → that status. Throw ValidationError/NotFoundError for 400/404. (Step 3.)
4. convertEntitiesToPojo only unwraps narrow shapes. A BNote nested under result.notes[], result.parentNote, result.attributes[] serializes raw/broken — call .getPojo() yourself or shape under note/branch. (Step 4.)
5. Core handlers must be browser-safe: no process.env (use getPlatform().getEnv()), no node:path/import path (use services/utils/path.ts extname/basename), no Node built-ins.
6. Registration order matters cross-runtime — register a literal path before a same-method :param catch-all on the same prefix. (Step 5.)
7. Don't write the test by hand — core route ⇒ CoreApiTester; Express transport ⇒ supertest. Hand off to the writing-unit-tests skill. (Step 6.)

Step 1 — Decide: core-shared vs server-only

The server-only set is small and specific — clipper, database, llm_chat, ocr, metrics, sender, totp, fonts, link_embed, recovery_codes, system_info, etapi_tokens, plus a few files extras. See the register() body in routes.ts (the shared set is wired by buildSharedApiRoutes at routes.ts:97). Everything else is core.

Browser-safe rule for core handlers: no process.env, no node:path/import path, no Node built-ins — they run in the sqlite-wasm standalone build. (script.ts:75,86 reads process.env.TRILIUM_SAFE_MODE directly — that is a latent violation, not a pattern to copy.)

Step 2 — Pick the wrapper

All four wrappers live in apps/server/src/routes/route_api.ts (apiRoute:69, asyncApiRoute:73, route:77, asyncRoute:81). Their names arrive via the buildSharedApiRoutes context object, so registering once in index.ts auto-wires all three call sites (server routes.ts:97, standalone browser_routes.ts:281, api_tester.ts:264).

A fifth name, asyncRouteWithoutTransaction, is also in the context object (index.ts:84) — use it for a long-running async handler that must not hold a transaction open.

The sync-transactional trap (route_api.ts:100):

return transactional ? sql.transactional(cb) : cb();

apiRoute → route(...true) → internalRoute(..., transactional=true); asyncApiRoute → asyncRoute(...false) → transactional=false. So apiRoute calls sql.transactional(cb) synchronously. If cb is async, sql.transactional sees a returned Promise, commits the (empty) transaction, and your awaited writes run after the commit, outside any transaction. The standalone adapter documents this exact trap in browser_routes.ts:127-133 ("would commit an empty transaction immediately when passed an async callback"). Async handler ⇒ asyncApiRoute. Always.

Auth/CSRF: apiRoute/asyncApiRoute attach auth.checkApiAuth + csrfMiddleware automatically (route_api.ts:70,74). Mutating endpoints therefore carry CSRF for free. Routes called from outside a browser session (setup, sync, sender, image/file download) use bare route()/asyncRoute() with an explicit [middleware] array (often checkApiAuthOrElectron or checkApiAuth) — see the route(...)/asyncRoute(...) registrations in index.ts and routes.ts.

Step 3 — Return value conventions

From apiResultHandler (route_api.ts:29-47), mirrored by the standalone apiResultHandler (browser_routes.ts:227) and CoreApiTester.formatApiResult (api_tester.ts:100):

Direct-response handlers (image/download) write to res themselves and use route(), not apiRoute() — see the direct-response registrations in index.ts.