API

Key Ideas

• Local Daemon Contract: the API is primarily the contract between surfaces and the local Refine daemon.
• Capability Groups: routes should map to real system capabilities, not arbitrary page needs.
• Surface Alignment: browser, CLI, desktop, and agent integrations should share API behavior where appropriate.
• Not A SaaS Boundary By Default: the API should not imply that Refine must become a centralized hosted service.
• Recoverable Mutations: API writes should flow through shared services with idempotency, logging, and state repair where needed.

Purpose

The API exists so surfaces can talk to the local daemon consistently. It gives browser JavaScript, CLI daemon routing, desktop wrappers, and future agent integrations a shared way to access project status, work items, workflow, processes, chat, settings, files, terminal sessions, diagnostics, and more.

The API should be treated as local capability plumbing. It is important, but it is not the product center.

Expected Role

The API should expose system capability groups that match Refine's product design. Current route groups include system, apps, project, target app, work, workflow, activity, import, dashboard, agents, operations, runner workers, processes, events, quality, chat, settings, governance, guidance, reporters, Reporter-scoped todos, nodes, cluster, changes, cache, performance, files, terminal, diagnostics, and upgrade.

Those groups are useful because they map surfaces onto shared behavior. They should not drift into page-specific endpoints when a shared service would express the capability better.

Daemon lifecycle routes use the shared host authority. Start may return its observed result directly. Stop and restart first persist and return a port-scoped operation receipt, then a restart-safe helper performs service control outside the daemon's systemd control group or launchd job. A caller can read the durable lifecycle operation after shutdown or reconnection and obtain the same observed status, lifecycle evidence, failure, and recovery guidance as a synchronous CLI caller.

Plan-to-Goal drafting uses the shared /import/extract route with purpose plan_goal; it returns exactly one unpersisted Goal draft so browser, CLI, and agent adapters can preserve their own explicit review boundary.

The Goals screen sends its filter-scoped bulk selection to POST /work/goals/export/jira, which returns a durable operation immediately. The supervised runner records ownership, progress, logs, cancellation, failures, and the completed Jira CSV result; interrupted exports can be retried through /work/goals/export/jira/{operation_id}/retry. The result contains one row per selected Goal plus the filename, content type, selected Goal ids, and aggregate counts. Existing single-Goal CLI and agent adapters reuse the same row renderer and evidence rules rather than formatting separate reports. That renderer budgets every Description to Jira's Unicode-character limit, prioritizes audit identity and commit traceability before normalized round outcomes and narrative, and marks every shortened section or field explicitly. Raw provider payloads are not replayed, and verbose history in one Goal must not fail the rest of a valid bulk selection.

The API should remain local-first. It should be secure by context, constrained by local daemon ownership, and careful about which operations mutate target state.

Future Direction

Future agent-native surfaces may use the API directly or through a higher-level protocol. The API should be structured enough for automated discovery and stable enough that agents can rely on it.

If Refine later supports distributed or hosted operation, the API may become a stronger remote contract. That should be an intentional scale step, not an accidental consequence of browser implementation.