Skip to content

feat: local REST/automation API (ETAPI-equivalent) #232

Description

@tstapler

Problem

SteleKit has no programmatic API for reading/writing the graph from outside the app itself. Trilium Notes ships ETAPI, a built-in REST API for exactly this (https://docs.triliumnotes.org/user-guide/advanced-usage/etapi) — scripting, third-party tool integration (Raycast/Alfred-style launchers), and automation all build on it.

This gap is already implicitly called out by an existing plan: project_plans/git-smart-sync/requirements.md lists as gap #3 "No CLI entry point: There is no way to trigger a sync cycle from a shell script, cron job, or CI pipeline. This blocks automation workflows." A local HTTP API is the more general solution to that same underlying need — a CLI can be a thin wrapper over it, and it additionally unblocks the web clipper (#230 in this repo) and any future third-party integrations without inventing a bespoke protocol per feature.

Why this matters

  • Currently three separate feature areas (git-smart-sync's automation ask, the web clipper's need for a write path, and any future LLM-tool-calling integration per project_plans/llm-service/) would each need their own local IPC mechanism without this. A single local API serves all three.
  • Local-first tools in this category (Obsidian Local REST API plugin, Logseq's local HTTP API) all converge on the same pattern: a localhost-bound, token-authenticated HTTP server exposing CRUD over pages/blocks.

Suggested scope (v1)

  • Localhost-only HTTP server (JVM/Desktop target first; mobile/WASM out of scope for v1), bound to a local port, off by default.
  • Token-based auth (generated locally, shown once, stored via existing platform secure-storage patterns).
  • Endpoints: list/get/create/update page, create/update block, basic query (can build on the live-query executor in feat: execute {{query}} blocks as live, auto-updating results #224 once it exists).
  • A thin CLI (stelekit sync, stelekit get <page>, etc.) as a client of this API, satisfying git-smart-sync's automation-entry-point requirement.
  • Out of scope for v1: remote/network-exposed access, webhook/event subscriptions, full ETAPI parity.

References

  • project_plans/git-smart-sync/requirements.md — states the CLI-entry-point need this API would satisfy
  • Enables: web clipper (feat: web clipper browser extension #230), and future LLM tool-calling per project_plans/llm-service/requirements.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions